OPNSEC—Establish a session, application program acts as the SLU

Purpose

The OPNSEC macroinstruction is issued by a VTAM® application program that has received a BIND request in a SCIP exit routine, and wants to respond positively to the BIND and thus establish a session with the PLU that sent the BIND. The application program that issues OPNSEC is the SLU in the session.

For a detailed description of the operation of the OPNSEC macroinstruction, refer to OPNSEC macroinstruction.

Usage

Before issuing the OPNSEC macroinstruction, the application program must set register 13 to the address of an 18-word save area. Refer to Summary of register usage, for information pertaining to the register contents upon return of control.

VTAM receives control from the OPNSEC macroinstruction in the addressing mode of the application program that issued the macroinstruction and returns control to the application program in that same mode.

When the OPNSEC successfully completes, VTAM indicates in the NIB the type of encryption (selective or required) that is specified by the application.

When the application is participating as a member of a generic resource, it can specify whether it wants to own the affinity for the new session. The application does this using the LUAFFIN keyword of the NIB macroinstruction. For more details see NIB—Create a node initialization block.

Syntax


>>-+------+--OPNSEC--RPL--=--rpl_address------------------------>
   '-name-'                                

>--+----------------------------+------------------------------->
   |                        (1) |   
   '-,--ACB--=--acb_address-----'   

>--+---------------------------+-------------------------------->
   |                       (1) |   
   '-,--BRANCH--=--+-NO--+-----'   
                   '-YES-'         

>--+--------------------------------------+--------------------->
   |                     (1)              |   
   +-,--ECB--=--INTERNAL------------------+   
   +-,--ECB--=--ecb_address---------------+   
   |                                  (1) |   
   '-,--EXIT--=--exit_routine_address-----'   

>--+----------------------------+------------------------------->
   |                        (1) |   
   '-,--NIB--=--nib_address-----'   

>--+----------------------------------------+------------------><
   |          (1)         (2)               |   
   '-,--OPTCD------=--(------+-+-ASY-+-+--)-'   
                             | '-SYN-' |        
                             '-+-CA-+--'        
                               '-CS-'

Notes:

Operand value can be placed in its RPL field either by specification on an RPL macroinstruction operand or by explicitly setting the field using the IFGRPL DSECT.
You can code more than one suboperand on OPTCD, but code no more than one from each group.

Input parameters

RPL=rpl_address: Indicates the RPL that specifies which kind of processing OPNSEC is to perform.

The following RPL operands apply to the OPNSEC macroinstruction:

ACB=acb_address

Indicates the ACB that identifies the application program issuing OPNSEC.

BRANCH

For application programs running in supervisor state under a TCB, BRANCH indicates whether authorized path processing is to be used. See Authorized path.

BRANCH=YES: When the macroinstruction is issued, VTAM processes the macroinstruction using authorized path. For programs running under an SRB rather than under a TCB, the macroinstruction is processed in this manner automatically, regardless of the actual setting of the BRANCH field.
BRANCH=NO: When the macroinstruction is issued, VTAM does not process the macroinstruction using authorized path.

ECB

Indicates that an ECB is posted when an asynchronous (OPTCD=ASY) OPNSEC operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction.

ECB=event_control_block_address: Specifies that VTAM is to post an event control block (ECB). Event_control_block_address is the location of the ECB to be posted. The ECB can be any fullword of storage aligned on a fullword boundary.
ECB=INTERNAL: Specifies that VTAM is to post an internal ECB.

EXIT=exit_routine_address

Indicates the address of an RPL exit routine that is scheduled when an asynchronous (OPTCD=ASY) OPNSEC operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction. For details about the EXIT operand, refer to the RPL macroinstruction description in this chapter.

NIB=nib_address

Indicates the NIB whose parameters are to be associated with the session requested by the BIND request. Refer to the NIB macroinstruction description in this chapter to see which NIB parameters are valid for OPNSEC.

OPTCD=CA

OPTCD=CS

Specifies the initial CA-CS setting of all input types (DFSYN, DFASY, and RESP) for the session. When CA is set, input received satisfies a RECEIVE OPTCD=ANY or OPTCD=SPEC. When CS is set, input received satisfies only a RECEIVE OPTCD=SPEC.

OPTCD=SYN

OPTCD=ASY

When SYN option code is set, control is returned to the application program when the OPNSEC operation has been completed. If ASY option code is set, control is returned as soon as VTAM has accepted the request. After the OPNSEC operation has been completed, the ECB is posted or the RPL exit routine is scheduled, depending on the setting of the ECB-EXIT field. Refer to the RPL macroinstruction description in this chapter for details about OPTCD=SYN or OPTCD=ASY.

Because it might take VTAM a relatively long time to complete the OPNSEC operation, you should not use the SYN option if suspending the OPNSEC-issuing task or SRB for this time is undesirable. Use the ASY option code, instead.

Examples

OPNS1    OPNSEC RPL=RPL1,OPTCD=CA,NIB=NIB1                             C
⋮
RPL1     RPL   AM=VTAM
NIB1     NIB   NAME=APPLPRI

Executing OPNS1 signifies acceptance of the session parameters received as a result of a BIND request and agreement to act as the secondary end of the session with APPLPRI.

Completion information

For selective and required cryptographic sessions, the OPNSEC operation is completed when the response to CRV is sent. For other sessions, completion occurs when the positive response to BIND is sent. Be aware that the RPL exit routine can be driven after other exit routines dealing with the same session are driven (for example, SCIP with start data traffic).

After the OPNSEC macroinstruction is completed, the following fields in the NIB are set:

The CID field contains the 4-byte communication identifier.
The CON field is set to YES if the session is established; otherwise, it is set to NO.
The NAME field contains the symbolic name of the PLU from the BIND request.
If NQNAMES=YES, the NETID field contains the network identifier of the PLU from the BIND request.

After the OPNSEC operation is completed, the following RPL fields are set:

The value 42 (decimal) is set in the REQ field, indicating an OPNSEC request.
The CID is placed in the RPLARG field.
The address of the NIB that was specified in the NIB field is returned in the AREA field. The NIB field is overlaid by the ARG field that contains the CID. The NIB and the ARG fields occupy the same space in the RPL.
The RTNCD and FDB2 fields are set as indicated in Return codes and sense fields for RPL-based macroinstructions.
If the macroinstruction returns an error code, the SSENSEI, SSENSMI, and USENSEI fields can be set indicating system-sense information, system-sense modifier, and user-sense information. More information about these fields can be found in Return codes and sense fields for RPL-based macroinstructions.

Note: The USERFLD is not set for OPNSEC.

Registers 0 and 15 are also set as indicated in Handling errors and special conditions.