CLOSE—Close one or more ACBs

Purpose

The following are the significant results of successfully executing the CLOSE macroinstruction (when persistence is not enabled):

VTAM® no longer accepts any requests that refer to the ACB specified in the CLOSE macroinstruction. This ACB is effectively disassociated from VTAM. Outstanding requests are posted complete.
VTAM no longer maintains the association between the APPL entry known to VTAM and the ACB specified in this macroinstruction.
VTAM terminates every session that exists between the application program logical unit (represented by the ACB) and other logical units. Before CLOSE terminates a session, all communication activity is stopped and all pending communication requests are canceled.

The preceding conditions do not apply when persistence is enabled. Instead, the following occurs:

VTAM puts all active sessions in the recovery pending state.
VTAM terminates all queued and pending active sessions and, if PSTIMER is set on SETLOGON OPTCD=PERSIST, VTAM starts timing. If doing MNPS, the MNPS state in the coupling facility is set to "SNPS recovery pending".

The CLOSE macroinstruction can be applied to more than one ACB. CLOSE must be issued in the mainline program. VTAM prevents attempts to issue CLOSE in an RPL exit routine or in any of the asynchronous EXLST exit routines, such as the TPEND exit routine.

For cross-memory API users, the following conditions must be met:

CLOSE must be issued in non-cross-memory mode by mainline processing under TCB control.
CLOSE must be issued in the address space that becomes the primary address space during a cross-memory VTAM API request.

See Cross-memory application program interface (API) support for more information.

Usage

The ACB and its related storage (APPLID, password, EXLST, NIB, and application-ACB vector list) must be allocated in the same storage key. This key can be the storage key of the program status word (PSW) at the time OPEN was issued, or the storage key of the task control block (TCB).

The access-method-support and resource-information vector lists (described in Vector lists) must not be referenced after the CLOSE macroinstruction is issued.

For general information about the CLOSE macroinstruction, refer to Opening and closing an application program. For multitasking and multiple address space considerations involving the CLOSE macroinstruction, refer to Operating system facilities.

Control block fields referenced by the CLOSE macroinstruction can reside in either 31-bit or 24-bit storage but must be consistent with the addressing mode of the application program. The MODE parameter is used to set the addressing mode of the ACB control block for these macroinstructions.

Because further considerations apply, VTAM must issue the list or execute form of the CLOSE macroinstruction.

The standard form of the CLOSE macroinstruction expands at assembly time into (1) nonexecutable code that represents the parameters you specified on the macroinstruction and (2) executable code that causes the access method to be entered when the macroinstruction is executed. The nonexecutable code, called the parameter list, is assembled at the point in your application program where the macroinstruction appears.

List and execute forms of the CLOSE macroinstruction cause the assembler to:

Build the parameter list where the macroinstruction appears in your source code, but assemble no executable code (list form)
Assemble code that modifies a parameter list and causes the access method to be entered during program execution (execute form).

Table 1 summarizes the actions of these various forms. It also indicates the types of programs that would use each form and shows the use of the MF operand. Below the table is the list and execute form of the close macroinstruction.

Table 1. Forms of the CLOSE macroinstruction
Form	During assembly	During execution	Useful for	Coded with
Standard	Parameter list built where macroinstruction appears in source code.	Access method entered.	Non-reentrant programs that are not sharing or modifying parameter lists.	No MF operand
List	Parameter list built where macroinstruction appears in source code.	No executable code (execute form required).	Non-reentrant programs that are sharing or modifying parameter lists.	MF=L
Execute	Code assembled (where macroinstruction appears in the source code) to modify the parameter list whose address you supply.	Parameter list modified and the access method entered.	Programs using the list form.	MF=(E,address)

Syntax


>>-+------+--CLOSE--+-(--acb_address--)-+----------------------->
   '-name-'         '-(--acb_address--)-'   

>--+----------------------------------------------------------+-->
   '-,--MF--=--(--+-E--+-------------------------------+-+--)-'   
                  |    '-,--+-parameter_list_address-+-' |        
                  |         '-(--register--)---------'   |        
                  '-L------------------------------------'        

   .-,--MODE--=--(--24--)-.   
>--+----------------------+------------------------------------><
   '-,--MODE--=--(--31--)-'

Input parameters

acb_address

Indicates the ACB disassociated from VTAM.

Format: If you code only one address, you can omit the parentheses. You can code up to 255 addresses. Separate each ACB address with two commas.

Note: Issue one CLOSE macroinstruction to close VSAM ACBs in addition to VTAM ACBs. Include DCBs.

MF=E

Indicates use of the execute form of the CLOSE macroinstruction and existing parameter list.

parameter_list_address: Indicates the location of the parameter list used by the access method.
The execute form allows you to modify the parameter list between the generation of that parameter list and the invocation of the access method routines that use the parameter list. Only the execute form provides a means for you to modify the parameter list after it is built.
(register): Indicates the number of the register that will contain the parameter list address when the macroinstruction is executed.

MF=L

Indicates that the CLOSE macroinstruction creates a parameter list referred to by an execute-form instruction.

MODE

specifies the format of the CLOSE parameter list being generated.

24: specifies that a standard form (24-bit) parameter list address be generated. The parameter list must reside below 16 megabytes and point to an ACB residing below 16 megabytes.
31: specifies that a long form (31-bit) parameter list address be generated. This parameter value must be coded if the parameter list or the ACB control block resides above 16 megabytes.

Examples

CLOSE123 CLOSE (ACB1,,ACB2,,(7))

CLOSE123 closes ACB1, ACB2, and the ACB whose address is in register 7. All sessions with the application program logical units represented by these ACBs are terminated.

Completion information

When control is returned to the instruction following the CLOSE macroinstruction, register 15 indicates whether the CLOSE processing has been completed successfully.

Successful completion (meaning that all ACBs specified in the macroinstruction have been disassociated from VTAM) is indicated by a return code of 0.

Unsuccessful completion is indicated by the following register 15 values:

Value: Meaning
4 (X'04'): One or more ACBs were not successfully closed. Depending on the type of error, the OFLAGS field can indicate that the ACB is closed even though the CLOSE has failed (for example, the ACB might never have been opened).
8 (X'08'): One or more ACBs were not successfully closed. Inspect the ERROR field for the cause of the failure. Another CLOSE macroinstruction can be used.
12 (X'0C'): One or more ACBs were not successfully closed. Another CLOSE macroinstruction cannot be issued.

Use the following guidelines to determine whether the CLOSE was successful:

Put 0 in register 15 before issuing CLOSE.
Issue CLOSE for only one VTAM ACB at a time.
If register 15 is 0, consider the CLOSE successful. If register 15 is not 0, consider the CLOSE unsuccessful, and examine the contents of the ACBs ERROR field.

If unsuccessful completion is indicated, the application program can examine the OFLAGS field in each ACB to determine which ACB was not closed. If you use the OFLAGS=OPEN operand on a TESTCB macroinstruction, an “equal” PSW condition code results if the previously opened ACB was not closed.

For each ACB, you can use either the SHOWCB or TESTCB macroinstruction to check the ERROR field and determine the cause of the error. For example:

SHOWCB
AM=VTAM,ACB=ACB1,FIELDS=ERROR,AREA=SHOWIT,             C
       LENGTH=4

Note: If the ACB address specified in the CLOSE macroinstruction does not indicate an ACB, or lies beyond the addressable range of your application program, the ERROR and OFLAGS fields in the ACB are unchanged.

The value set in the ERROR field of the ACB specified in the CLOSE macroinstruction indicates the specific nature of the error (if any) found.

ERROR field: Meaning
0 (X'00'): CLOSE successfully closed the ACB.
4 (X'04'): A CLOSE macroinstruction has been successfully issued for this ACB (or the ACB has never been opened in the first place).
20 (X'14'): CLOSE cannot be processed because of a temporary shortage of storage.
64 (X'40'): Outstanding OPNDST OPTCD=ACQUIRE is not released.
66 (X'42'): The ACB has been closed, but an apparent system error has prevented the successful termination of one or more of the sessions that the application program has. There is a logic error in VTAM; consult IBM® Service. The LUs that have not had their sessions terminated are not available to other application programs, and LUs with which you were requesting a session when the CLOSE macroinstruction was issued are likewise unavailable. You can notify the VTAM operator (while the program is running) of the situation so that the operator can make the LUs available to other application programs.
70 (X'46'): CLOSE was not issued in the mainline program. OPEN and CLOSE cannot be issued in any exit routine.
76 (X'4C'): This application program is authorized to issue VTAM operator commands and receive VTAM messages. A CLOSE was issued, but messages are still queued for it, or VTAM is waiting for a reply, or both. See Orderly closing of a program operator for more information.
80 (X'50'): VTAM is no longer included as part of the operating system.
96 (X'60'): An apparent system error occurred. Either there is a logic error in VTAM; or there is an error in your use of OPEN or CLOSE that VTAM did not properly detect. Save all applicable program listings and storage dumps, and consult IBM Service.
112 (X'70'): CLOSE was issued while the program was in the process of terminating abnormally. The CLOSE is not necessary because the ACB is closed by VTAM when the task terminates.
188 (X'BC'): The ACB is in the process of being opened or is in the process of being closed by another request.