OPEN—Open one or more ACBs

Purpose

The OPEN macroinstruction opens an ACB so that the ACB and all subsequent requests referring to it can be identified by VTAM® as applying to a specific application program. During OPEN processing, the application program cannot issue requests that reference the ACB. You indicate the ACB that is to be opened in the OPEN macroinstruction coding.

Usage

After the OPEN macroinstruction completes successfully, VTAM sets the fields of the ACB that point to the access-method-support and resource-information vector lists. The application program can reference these fields until a CLOSE macroinstruction or equivalent (for example, ABEND) occurs. Vector lists describes the vector lists.

Because an application program can start before VTAM starts, an application program might issue an OPEN macroinstruction before VTAM is active. In this case, OPEN fails and the application program is informed that VTAM is not active. This is the only way an application program can determine whether VTAM is active.

An application that has enabled persistence can use OPEN to recover sessions pending recovery. See Using persistent LU-LU session support for more information.

OPEN must be issued in the mainline program.

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

OPEN must be issued in non-cross-memory mode by mainline processing under TCB control.
OPEN 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.

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).

VTAM prevents attempts to issue OPEN in an RPL exit routine or in any of the other asynchronous exit routines. For additional information about the OPEN macroinstruction, see Opening and closing an application program.

VTAM supports application programs in 31-bit addressing mode and residing in 31-bit storage. Control block fields referenced by the OPEN 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, you must issue the list or execute forms of the OPEN macroinstruction.

The standard form of the OPEN 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.

The list and execute forms of the OPEN 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 cause 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 how the MF operand is used for each form.

Table 1. Forms of the OPEN 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)

The OPEN macroinstruction can specify up to 255 ACB addresses and is used to construct a data management parameter list. The parameter list is assembled where the macroinstruction appears in the source code.

The list consists of a one-word entry for each ACB in the parameter list; the three low-order bytes are used for the ACB address. The end of the list is indicated by a 1 in the high-order bit of the last entry's high-order byte. The length of a list generated by a list-form instruction must be equal to the maximum length required by an execute-form instruction that refers to the same list.

Syntax

This standard form of OPEN is valid.


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

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

This is the list and execute form.


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

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

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

Input parameters

acb_address

Indicates the ACB that is to be associated with an APPL entry.

Format: If you specify more than one ACB, separate each with two commas. No more than 255 ACB addresses may be specified.

You can omit the parentheses if you code only one address.

Note: VSAM ACB addresses can also be used in the OPEN macroinstruction. Users can code DCB addresses. You can combine the addresses of different types of control blocks in one OPEN macroinstruction.

MF=E

Indicates that the execute form of the OPEN macroinstruction and an existing parameter list are used. 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 has been built.

parameter_list_address: Indicates the location of the parameter list to be used by the access method.
(register): Indicates the number of the register that will contain the parameter list address when the macroinstruction is executed.

MF=L

Indicates that the OPEN macroinstruction is used to create a parameter list referred by an execute-form instruction.

MODE

specifies the format of the OPEN 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

OPEN123 OPEN (ACB1,,ACB2,,(7))

OPEN123 opens ACB1, ACB2, and the ACB whose address is contained in register 7. Each of these ACBs is linked with an APPL definition statement.

Completion information

When control is returned to the instruction following the OPEN macroinstruction, register 15 indicates whether the OPEN processing was completed successfully. Successful completion means that all ACBs specified in the OPEN macroinstruction were opened; unsuccessful completion means that at least one ACB was not opened. Successful completion is indicated by a return code of 0 in register 15. The following register 15 values indicate unsuccessful completion:

4 (X'04'): All ACBs were successfully opened, but warning messages were issued for one or more VSAM ACBs.
8 (X'08'): One or more ACBs were not successfully opened. If the error condition indicated by the unopened ACB's ERROR field can be eliminated, another OPEN macroinstruction can be issued for the unopened ACBs.
12 (X'0C'): One or more ACBs were not successfully opened. Another OPEN macroinstruction cannot be issued for the unopened ACBs.

If unsuccessful completion is indicated, the application program should examine the OFLAGS field in each ACB to determine which one (or ones) could not be opened. Test each OFLAGS field by coding an ACB address and OFLAGS=OPEN in a TESTCB macroinstruction; if the resulting PSW condition code indicates an equal comparison, that ACB has been opened:

TESTCB   ACB=ACB4,OFLAGS=OPEN

If an unequal comparison is indicated, meaning that the ACB has not been opened, the ERROR field can be checked to determine the reason. Like OFLAGS, ERROR is not a field that the application program should modify (that is, there is no ERROR operand for the ACB macroinstruction, and thus none for the MODCB macroinstruction), but the application program can obtain the contents of this field with the SHOWCB or TESTCB macroinstruction. For example:

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

Note: If the ACB is open, or if the address specified in the OPEN macroinstruction either 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. Thus, if you find one of the following return codes in the ACB's ERROR field and none of the specified causes apply, perhaps you are actually examining a field whose contents have not been modified by OPEN. An open ACB or an ACB address that is not valid results in register 15 being set to a nonzero value, however.

A list of the values that can be set in the ERROR field of an ACB follow (ACBERFLG is the actual field name). Because most of these error conditions result from an error in your application program or in the system programmer's definition of VTAM, little can be done during program execution when these return codes are encountered. If, however, you are attempting to open more than one ACB, you might want to check the ERROR field of each ACB. All ACBs whose ERROR fields are set to 0 have been opened successfully, and your application program can proceed using those ACBs.

The value set in the ERROR field of the ACB specified in the OPEN macroinstruction indicates the specific nature of the error (if any) found. Except where noted, all values apply to all operating systems.

ERROR field

Meaning

0 (X'00')

OPEN successfully opened this ACB.

4 (X'04')

The ACB has been opened.

20 (X'14')

OPEN cannot be processed because of a temporary shortage of storage.

36 (X'24')

The OPEN ACB failed for one of the following reasons:

The password specified by the ACB did not match the corresponding password in the APPL entry.
The ACB did not specify a password and the APPL contains one.
The security management product determined that the user is not authorized to open the ACB.

70 (X'46')

OPEN was issued in an exit routine.

80 (X'50')

VTAM has not been included as part of the operating system. The fault lies in the system definition procedures.

82 (X'52')

VTAM is included as part of the operating system, but the VTAM operator issued a HALT command, and VTAM has shut down. You cannot attempt to establish a session or communicate with any LUs.

84 (X'54')

Either the address supplied in the ACB's APPLID field lies beyond the addressable range of your application program, or no entry is found in the VTAM configuration tables that matches the name indicated by the ACB's APPLID field (or supplied by the operating system). If the OPEN macroinstruction is specified correctly, your system programmer might have:

Failed to include your application program's symbolic name during VTAM definition
Improperly handled the symbolic name.

Refer to the description of the APPLID operand in ACB—Create an access method control block.

86 (X'56')

A match for your application program's symbolic name is found, but it is for an entry other than an APPL. If you specified this name in the ACB's APPLID field, verify that you have the correct name and handled this name properly (see the APPLID operand of the ACB macroinstruction). If the symbolic name is supplied by the operating system, the supplied name is suspect.

88 (X'58')

Another ACB, already opened by VTAM, indicates the same application program symbolic name that this ACB does. The system programmer might have assigned the same symbolic name to two application programs. This is valid only if the programs are not open concurrently. Possibly the system operator initiated your program at the wrong time.

90 (X'5A')

No entry is found in the VTAM configuration tables that matches the name indicated by the ACB's APPLID field (or supplied by the operating system). This error might have occurred for one of the following reasons:

The VTAM operator deactivated the APPL entry.
The APPL entry was never created.
If VTAM is trying to recover for persistent sessions, the application is not in pending recovery state.

92 (X'5C')

VTAM is included as part of the operating system but inactive.

94 (X'5E')

The address supplied in the ACB's APPLID field lies beyond the addressable range of your application program.

95 (X'5F')

The VTAM transient being used by the application for an OPEN ACB does not match the level of VTAM.

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.

98 (X'62')

The APPLID length byte is incorrectly specified.

100 (X'64')

The address supplied in the ACB's PASSWD field lies beyond the addressable range of your application program.

102 (X'66')

The PASSWD length byte is incorrectly specified.

104 (X'68')

The APPLID field in the ACB identifies an application program that is defined with AUTH=PPO in its APPL definition statement. Another program with the same authorization is active. Only one program defined with AUTH=PPO can be active at a time.

106 (X'6A')

The address supplied in the ACB's vector list field lies beyond the addressable range of your application program.

108 (X'6C')

The VTAM ACB vector list length byte is incorrectly specified.

112 (X'70')

You attempted to open an ACB that is in the process of being closed. This can occur when a VTAM application program job step or subtask is canceled or terminates abnormally. The process of closing the ACB can continue after the job step or subtask has actually terminated. Subsequently, if the job step is restarted or the subtask is reattached before the ACB closing process has been completed, an OPEN macroinstruction that is then issued for that ACB fails.

114 (X'72')

This code occurs when an OPEN ACB fails for an LU 6.2 application with VERIFY=OPTIONAL or VERIFY=REQUIRED for one of the following reasons:

The security management product is not installed.
The security management product is not active.
The security management product resource class APPCLU is not active.
The application represented by the ACB is not in the security management product Started Procedures Table.

116 (X'74')

VTAM rejected the takeover by an alternate application because the original application did not enable persistence, although it is capable of persistence.

118 (X'76')

OPEN failed because the specified application is in a recovery pending state and PERSIST=YES is not specified on the ACB that is being opened. The OPEN may also fail if the application is in pending terminate state and an active CDRSC with the same name has been found in the sysplex.

120 (X'78')

ACB option mismatch between original application and opening takeover or recovery application. One or more of the following can apply:

MACRF mismatch—both values must be either LOGON or NLOGON; they cannot differ.
NQNAMES mismatch—both applications must be specified as NQNAMES=YES or NQNAMES=NO; they cannot differ.
PERSIST mismatch—both applications must be specified as PERSIST=YES.
FDX mismatch—both applications must be specified as FDX=YES or FDX=NO; they cannot differ.
LIMQSINT mismatch—both application APPL statements must agree in their specification of a LIMQSINT parameter; either both must specify a value or neither may. (The actual timer values specified do not need to be identical, however.)
APPC mismatch — both application APPL statements must specify either APPC=YES or APPC=NO; they cannot differ.
ENCR or MAC mismatch—the recovering application APPL statement must specify a security level equal to or higher than the setting in effect for the original application
GNAME capability mismatch—the original application was supporting a generic name but the VTAM node of the recovering application is not connected to a generic resource structure or its structure name differs from the original structure name.
SECLVL mismatch—both application APPL statements must specify the same SECLVL setting values; they cannot differ.
VERIFY mismatch—both application APPL statements must specify the same VERIFY setting values; they cannot differ.

122 (X'7A')

The OPEN ACB by this performance monitor application failed because a performance monitor application was already active, and only one performance monitor application can be active.

124 (X'7C')

SNPS takeover request denied because the active application does not allow itself to be taken over when it is still active.

140 (X'8C')

PERFMON=YES is coded on the ACB but the application is not CNM and POA authorized.

188 (X'BC')

The ACB is in the process of being opened or closed by another request.

244 (X'F4')

The application program is not authorized for SRBEXIT=YES. A request to open an ACB whose corresponding APPL definition statement specifies SRBEXIT=YES is rejected unless the application program is APF authorized, or using key 0–7, or in supervisor state.

246 (X'F6')

NIB storage address not valid. A CNM authorized application program either failed to supply an NIB pointer in the NIB field of the ACB, or the NIB address supplied lies beyond the addressable range of the application program.

250 (X'FA')

NIB options not valid. Either an application program without CNM authorization (specified in its associated VTAM resource definition) supplied an NIB pointer in its ACB; or, if CNM authorized, the application program failed to supply valid NIB options on the NIB macroinstruction.

254 (X'FE')

Duplicate unsolicited RU routing requested. The CNM routing table indicated that this application program was to receive the same unsolicited formatted requests that were already being routed to another active CNM authorized application program. Only one application program can be actively receiving a particular type of RU (for example, RECFMS) at a time.

The OFLAGS field in the ACB is set to B'xxx1xxxx' if the ACB opens successfully.

Use the following guidelines to produce a system-independent determination of a successful or unsuccessful OPEN:

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

For a CNM application program, the CID of the SSCP-LU session is returned in the CID field of the NIB specified in the ACB's PARMS=(NIB=nib address) operand.