Purpose

The ACB control block identifies the application program to VTAM® and to the SNA network as a logical unit.

Usage

You must define each application program before the program can use VTAM to communicate with logical units throughout the network. You define an application program by coding an APPL definition statement for the program. The application program must then create an ACB that points to the same symbolic name of the program as the name specified by the APPL statement. When the ACB is opened, VTAM finds the APPL information for the program and associates that information (that is, associates the application program) with the ACB.

Each application program that uses VTAM must define and open an ACB. An application program can contain more than one ACB (thus breaking itself down into "subapplications"), but each ACB must indicate a different application program name (that is, identify a separate APPL definition statement).

After the ACB has been opened, requests for VTAM services, such as requests for session establishment, requests for communication operations, and requests for network management (if the application program is authorized), can be made. When the ACB is closed (with the CLOSE macroinstruction) such requests can no longer be made, and any sessions that were established are terminated.

Using the ACB, the application program can provide an address of a list of exit routine addresses. The routines represented in this list are invoked by VTAM when special events occur, such as error conditions or session-establishment requests.

Using the ACB, the application program can also cause VTAM to prevent or allow certain session-establishment requests that are directed to the ACB.

If this application program is an authorized communication network management (CNM) program, the ACB can identify an NIB to be used to allow access to the SSCP-LU session established when the ACB is opened.

The application program can also specify 4 bytes of user data placed in the ACB. This data is not examined by VTAM.

An ACB macroinstruction causes an ACB to be built during program assembly on a fullword boundary. The ACB can also be built during program execution with the GENCB macroinstruction. The ACB is modified during program execution with the MODCB macroinstruction, or by using the DSECT created by the IFGACB mapping macroinstruction, but only before the ACB opens. Do not modify the ACB while it is open. Not all ACB fields can be created or accessed by the manipulative macroinstructions.

The ACB control block referenced by the OPEN and CLOSE macroinstructions 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.

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

For each ACB opened to VTAM, there is approximately X'250' bytes of storage used as a VTAM work area. This work area is released when CLOSE ACB processing completes.

An application program can indicate its capacity to support persistent sessions by specifying (PARMS=(PERSIST=YES)). In addition, the application can indicate that the OPEN ACB associated with this ACB should be permitted to initiate MNPS forced takeover processing, if necessary, by specifying (PARMS=(FORCETKO=YES)).

For additional information about the ACB, see Opening and closing an application program.

Input parameters

AM=VTAM

Identifies the ACB built by this macroinstruction as a VTAM ACB. This operand is required.

APPLID=application_program's_symbolic_name_address

During OPEN processing, links the ACB with a particular entry in VTAM's configuration tables that was created by an APPL definition statement. This both identifies the application program to VTAM and associates the application program with any options that might be indicated on the APPL statement.

If APPLID is coded, the symbolic name must match either the ACBNAME parameter (if coded) or the name field on the APPL definition statement. If ACBNAME has not been coded, APPLID must match the APPL statement's name field.

If the ACBNAME operand has been omitted, APPLID (and the name field of the APPL statement) must be a network-unique name for the application to have cross-domain sessions. If ACBNAME is coded, ACBNAME and APPLID must be unique only to their domain.

If an application program name is not specified on the APPLID operand of the ACB macroinstruction, VTAM uses a name supplied by the operating system. If the name supplied by the operating system does not match a name on the APPL definition statement, VTAM does not process the ACB.

If the application program is started by a job step that is a procedure invocation, the name is the procedure step name in the job control language (JCL) for the application program. Otherwise, it is the job step name in the JCL.

Format: Expressions involving registers cannot be used with the ACB macroinstruction.

Note: The area pointed to by this operand must begin with a 1-byte length field followed by the application program's symbolic name in EBCDIC. This is the symbolic name that appears in an APPL statement (name or ACBNAME operand), and must conform to the rules for coding this operand described in the z/OS Communications Server: SNA Resource Definition Reference. The length field specifies the length of the name. Any name that is longer than 8 bytes is truncated to 8 bytes. You can either pad the name to the right with enough blanks to form an 8-byte name (length field of 8), or you can set the length field to the actual length of the name you are providing and let VTAM do the padding. In the example at the end of this macroinstruction description, the first method is used.

The area pointed to by this operand must reside in 24-bit addressable storage.

EXLST=exit_list_address

Links the ACB to an exit list containing addresses of routines to be entered when certain events occur. This list is created by an EXLST (or GENCB) macroinstruction. See EXLST—Create an exit list for a more complete description of this macroinstruction. You can also refer to Using exit routines, for descriptions of these events.

More than one ACB can indicate the same exit list. For more information, see EXLST—Create an exit list. If no exit list is used, the application program is not notified that all the events described in the EXLST macroinstruction occurred.

The exit list identified in an ACB applies to all sessions with the application program. A separate exit list can be identified in the NIB used when the session is established to specify a DFASY, RESP, or SCIP exit routine (or any combination) to be used for that particular session. For details, refer to Specifying the DFASY, RESP, and SCIP exit routines in an ACB or NIB.

Format: Expressions involving registers cannot be used with the ACB macroinstruction.

MACRF

Indicates whether the application program can act (1) as the PLU in any LU-LU session other than those that it initiates itself through OPNDST OPTCD=ACQUIRE and (2) as the SLU in any LU-LU session.

An application program that is recovering for a failing application program must have the same MACRF value as the failing application program.

MACRF=LOGON

Indicates whether the application program can act (1) as the PLU in any LU-LU session other than those that it initiates itself through OPNDST OPTCD=ACQUIRE and (2) as the SLU in any LU-LU session.

MACRF=NLOGON

If NLOGON is specified, the only LU-LU sessions allowed for the application program are those initiated by the application program itself using OPNDST OPTCD=ACQUIRE. Thus, if NLOGON is specified, the application program cannot issue SIMLOGON or REQSESS, cannot have its SCIP exit routine scheduled with BIND requests sent by other LUs, and cannot receive CINITs (for instance, in a LOGON exit routine) because of sessions initiated by other LUs. NLOGON also prevents the operation of SETLOGON OPTCD=START, STOP, and QUIESCE. See also Table 1 for a summary of the interaction between SETLOGON and the ACB's MACRF operand.

Other application programs can interrogate for the setting of the MACRF operand by using INQUIRE OPTCD=APPSTAT. See the description of the INQUIRE macroinstruction.

PARMS=(APPLVCTR=vector_address)

Specifies the address of the application-ACB vector list. The application-ACB vector list contains a collection of vectors provided by the application to VTAM on the ACB macroinstruction. See Vector lists for more information.

If the application is recovering after a node failure, its application-ACB vector list must be identical to that of the original application program. See Opening the ACB during recovery from a node failure for more information.

PARMS=(FDX=YES|NO)

Specifies whether the application program supports LU 6.2 architecture protocol extensions for full-duplex and expedited data transmission. When starting the first session with a partner LU, the support or non-support information is used when negotiating LU-LU session support capabilities. If YES is specified, the application program handles requests for full-duplex conversations and receipt of expedited data RUs. If omitted, or if NO is specified, the full-duplex/expedited data extensions are not used on sessions with this application program.

If the application is recovering after a node failure, its support for LU 6.2 full-duplex protocols must match that of the original application. See Opening the ACB during recovery from a node failure for more information.

PARMS=(FORCETKO)

Indicates whether the application wants the OPEN ACB that is associated with this ACB to trigger MNPS takeover processing when the existing application image within the sysplex is not pending some form of MNPS recovery. This parameter is valid only if PARMS=(PERSIST=YES) is also specified.

PARMS=(FORCETKO=YES)

The application wants MNPS forced takeover processing to be performed when the existing application image in the sysplex does not require MNPS recovery processing.

PARMS=(FORCETKO=NO)

The application does not require MNPS forced takeover processing to be performed. Normal OPEN ACB (which could include MNPS planned takeover processing) logic should be performed for this ACB.

PARMS=(KEEPFRR)

Specifies whether VTAM maintains the FRR stack for an application-dispatchable unit of work while VTAM processes the work.

PARMS=(KEEPFRR=YES)

VTAM does not disturb the contents of the FRR stack when VTAM API gains control. VTAM returns the FRR stack intact when VTAM returns control to the application.

PARMS=(KEEPFRR=NO)

VTAM purges the FRR stack and adds its own FRRs. VTAM removes the added FRRs before returning control to the application.

VTAM must have at least one slot on the FRR stack; otherwise, z/OS® abends the SRB.

Note: In order to use the KEEPFRR function for macroinstructions issued with OPTCD=SYN under control of an SRB that is not running in cross-memory mode, use OPTCD=(SYN,KEEPSRB). For more information, see Additional coding considerations for authorized path.

PARMS=(NIB=nib_address)

Points to an NIB used to allow access to the SSCP-LU session. PARMS is initialized by a CNM application program prior to execution of the OPEN macroinstruction. This suboperand must be omitted for an application program that is not authorized for communication network management; in this case, the address field is set to 0. PARMS must specify a valid NIB address for an application program authorized for CNM. Refer to the OPEN macroinstruction ERROR field description of error codes 246 and 250 for further details. When an ACB is generated during program assembly for a CNM application program, the PARMS operand and the NIB suboperand initialize the ACBTNIB field with the NIB address.

When an ACB is generated during program execution, the GENCB macroinstruction allocates an ACB that includes the ACBTNIB field. However, manipulative macroinstructions cannot be used to initialize or modify the ACBTNIB field. Instead, the application program that dynamically initializes the ACB requires the IFGACB BAL mapping macroinstruction to map the ACB; the ACBTNIB label declared by the IFGACB macroinstruction is then used by the application program to initialize the field to the desired NIB address.

For more information about CNM application programs, see Handling errors and special conditions.

PARMS=(NQNAMES)

Specifies whether the application program understands and is using network-qualified names.

If the application program is recovering after a node or application failure, it must have the same PARMS=(NQNAMES) value as the original application program. See Opening the ACB during recovery from an application failure or Opening the ACB during recovery from a node failure for more information.

PARMS=(NQNAMES=YES)

For application programs that also specify APPC=NO, and for all non LU6.2 sessions, if PARMS=(NQNAMES=YES), the application program supports network qualified names, and can use both network-qualified names and non-network-qualified names. For example, an OPNDST with a non-network-qualified name works regardless of whether the application program has specified that it supports network-qualified names.

VTAM examines the NIBNET field (the same field previously used by NIBMODE) in the ISTDNIB control block. If the contents on NIBNET are not equal to "RECORD  ", and the field has not been set to blanks (X'40) or null (X'00), the value of NIBNET is used as the network identifier of the network qualified name (netid.luname). The luname is obtained from the field NIBSYM of ISTDNIB.

For application programs that specify APPC=YES then for all LU 6.2 sessions the following applies: the application program must provide network qualified names. That is, the PRL6NET field (NETID= ) must be filled in with the network identifier of the target on all APPCCMDs that also specify RPL6LU (LUNAME= ).

PARMS=(NQNAMES=NO)

The application program does not support network-qualified names and can use only non-network-qualified names. If a network identifier is provided in the NIB, it is ignored.

PARMS=(PERFMON)

Indicates whether the application is authorized to use the performance monitor interface.

PARMS=(PERFMON=YES)

The application is authorized to use the performance monitor interface.

PARMS=(PERFMON=NO)

The appplication is not authorized to use the performance monitor interface.

PARMS=(PERSIST)

Indicates whether the application can support persistent LU-LU sessions.

PARMS=(PERSIST=YES)

The application is capable of persistence, and VTAM tracks each request unit flowing on any LU-LU sessions established by the application.

PARMS=(PERSIST=NO)

The application is not capable of persistence. The latest RU information is kept.

PARMS=(SRBEXIT)

Specifies whether the application is authorized to use SRB processing in its exit routines. The SRBEXIT option enables an application to dynamically control whether SRB dispatching schedules user exits in SRB mode. SRBEXIT overrides what is coded on the APPL statement. If this operand is not specified, VTAM uses the APPL statement.

Note: If multiple applications open an ACB under one task, VTAM recognizes the SRBEXIT operand for the first application that opens the ACB. Therefore, the first open ACB determines whether exit routines operate in SRB or task control block (TCB) mode. This operand is ignored for subsequent applications opening ACBs under the same task. If you code SRBEXIT=YES on the first application opening the ACB, the subsequent applications opening ACBs under the same task must be authorized.

PARMS=(SRBEXIT=YES)

The application is authorized to use SRB processing in its exit routines.

PARMS=(SRBEXIT=NO)

The application is not authorized to use SRB processing in its exit routines.

PARMS=(USERFLD=user_data)

Can be any 4 bytes of data that the application program wants to associate with the ACB. The ACB macroinstruction stores this data in the ACBUSER field of the control block that the macroinstruction creates. The field can be referenced or changed at any time by the application program. VTAM does not examine this field.

The data can be coded in either character, fixed-point, or hexadecimal format, or, if an address is desired, it can be coded as an A-type or V-type address constant. Register notation cannot be used. If the operand is omitted, the user field is set to 0.

When an ACB is generated during program assembly, the PARMS operand and the USERFLD suboperand initialize the ACBUSER field with the user data. When an ACB is generated during program execution, the GENCB macroinstruction allocates an ACB that includes the ACBUSER field. However, manipulative macroinstructions cannot be used to initialize or modify the ACBUSER field. Instead, the application program that dynamically initializes the ACB requires the IFGACB BAL mapping macroinstruction to map the ACB; the ACBUSER label declared by the IFGACB macroinstruction is then used by the application program to initialize the field to the desired user data.

PASSWD=password_address

Allows an application program to associate its ACB with an APPL entry that is password protected. If a password is included in an APPL entry, any application program wanting to link its ACB to that entry must specify the entry's password in the ACB. The two passwords are compared when the application program opens the ACB. If the passwords do not match, the ACB is not opened. (The purpose of this password protection is to prevent a program from running as one of the installation's predefined application programs without the authorization of the installation.) If you omit this operand, the PASSWD address field is set to 0.

Note: The area pointed to by this operand must begin with a 1-byte length field followed by the EBCDIC password (in alphanumeric characters only). This is the password that is specified using the PRTCT operand of the APPL definition statement. It must conform to the rules for coding this operand described in the z/OS Communications Server: SNA Resource Definition Reference. The maximum length is 8 bytes. The truncation and use of the length field are the same as for the APPLID operand.

Format: Expressions involving registers cannot be used with the ACB macroinstruction.

Completion information