Purpose

The NIB is used during the initiation and establishment of LU-LU sessions to identify and define those sessions. Similarly, it is used to define the SSCP-LU session for a CNM application program. The NIB is also used to identify queued, pending active, or active sessions that the application program wants to terminate. Finally, it is used by the INQUIRE and INTRPRET macroinstructions to specify parameters that cannot be specified in the RPL.

Usage

For certain macroinstructions, NIBs can be grouped together into lists. When requests are directed to an NIB that is the first in an NIB list, VTAM® considers all of the logical units (LUs) represented in the NIB list to be the objects of the request, not just the LU represented by the first NIB.

The NIB macroinstruction causes the NIB control block to be built during program assembly; it is built on a fullword boundary. The NIB macroinstruction is not executable. An NIB can be built during program execution with a GENCB macroinstruction. It can be subsequently modified using the ISTDNIB and ISTDPROC DSECTs, and by the MODCB macroinstruction. MODCB does not, however, support all NIB fields.

The expansion of the NIB macroinstruction is identical for 24- and 31-bit addressing mode application programs.

Input parameters

AFFIN

Indicates whether VTAM or the application program is to be the owner of any affinities that are established for this instance of a generic resource being established by the SETLOGON OPTCD=GNAMEADD macroinstruction. The AFFIN parameter is mutually exclusive with the LUAFFIN parameter.

AFFIN=VTAM

Indicates that VTAM is to be the owner of any affinities not explicitly owned by the application program.

AFFIN=APPL

Indicates that the application program is to be the owner of all affinities that are established.

ASDAREA=dial_parameter_list_address

Specifies the address of the dial parameter list that is supplied by the application. The ASDAREA operand sets the NIBASDP and NIBASDPA fields. The NIBASDP field indicates that during session establishment the application supplies the dial parameters. The NIBASDPA field holds the dial parameter list address. You must use a fully initialized NIB for each established session. For additional information see Control block formats and DSECTs.

Note: VTAM can overwrite the NIBASDPA field during certain macroinstruction calls that use the NIB. For example, the persistent LU-LU session function uses the same 4-byte field as NIBASDPA to store the address of the recovery data when restoring sessions pending recovery.

BNDAREA=BIND_area_address

Permits the application program to explicitly specify a set of session parameters VTAM uses in constructing a BIND request or BIND response that is sent to establish a session.

BNDAREA=bind_area_address

Indicates the location of a BIND area containing session parameters to be used by OPNDST and OPNSEC macroinstructions. Session parameters specified in a BIND area generally override session parameters available from any other source. See Figure 1 for details. See also NIB LOGMODE and BNDAREA operands for details.

Note: BNDAREA and MTSAREA are mutually exclusive keywords on this macroinstruction.

BNDAREA=0

BNDAREA=0 must be specified, explicitly or by default, in the NIB used by a CNM application program to gain access to the SSCP-LU session.

ENCR

Indicates the level of cryptography that the application program requests for the session being established by OPNDST or OPNSEC. If either REQD or SEL is specified, the session is not established unless both ends of the session are capable of cryptography. Note that the actual level of cryptography used on the session can be higher than that specified by the ENCR operand, because the VTAM operator, the VTAM network definition, and the other LU in the session can all request upgrading of the cryptography level. See Establishing cryptographic sessions for more information.

ENCR=NONE

No enciphering is requested. ENCR=NONE must be specified, explicitly or by default, in the NIB used to give a CNM application program access to the SSCP-LU session.

ENCR=REQD

All data requests (STYPE=REQ, CONTROL=DATA) are sent enciphered.

ENCR=SEL

Data requests are to be enciphered on the basis of the RPL's CRYPT field setting. See the RPL macroinstruction description for further information on the CRYPT field.

EXLST=exit_list_address

Indicates an EXLST control block that contains the address of a DFASY, RESP, or SCIP exit routine (or contains the addresses of any combination of these exit routines).

Exit routines indicated by an NIB (NIB-oriented exit routines) are scheduled when VTAM receives input (of the appropriate type) from the session established by means of the NIB through an OPNDST, OPNSEC, or OPEN macroinstruction. If input is received and no appropriate NIB-oriented exit routine was specified, VTAM then satisfies any appropriate pending RECEIVE macroinstructions or schedules the appropriate ACB-oriented exit routine (if any). For details, refer to Specifying the DFASY, RESP, and SCIP exit routines in an ACB or NIB, and refer to Figure 1 through Figure 4.

Note: If you omit this operand, the NIB's EXLST field is set to 0.

GNAME=generic_name

is used to specify the generic name of the application. This field is used by the SETLOGON OPTCD=GNAMEADD, GNAMEDEL, or GNAMESUB, INQUIRE OPTCD=SESSNAME, and CHANGE OPTCD=ENDAFFIN macros. This name must be unique.

Note:

1. The NAME operand is required with SETLOGON OPTCD=GNAMESUB.
2. The GNAME parameter and the LOGMODE parameter are mutually exclusive.

LISTEND

Allows the application program to group NIBs into lists.

LISTEND=NO

Iindicates that this NIB and the NIB immediately following it in storage are part of an NIB list. Any number of NIBs can be grouped together by specifying LISTEND=NO for each one except the last. NIB lists can only be used with OPNDST OPTCD=ACQUIRE, or with SIMLOGON.

LISTEND=YES

Indicates that this NIB is the last in a list (or is an isolated NIB not part of a list).

Example: The following use of the LISTEND operand effectively groups the Boston NIBs into one group, the Chicago NIBs into another, and defines the Portland NIB as a “list” of one.

BOSTON   NIB   NAME=BOSTON1,LISTEND=NO
         NIB   NAME=BOSTON2,LISTEND=YES
CHICAGO  NIB   NAME=CHICAGO1,LISTEND=NO
         NIB   NAME=CHICAGO2,LISTEND=NO
         NIB   NAME=CHICAGO3,LISTEND=YES
PORTLAND NIB   NAME=PORTLAND,LISTEND=YES

LOGMODE

is used to specify the logon mode name. If this operand is either omitted or specified as 0, the LOGMODE field of the NIB is set to binary zeros.

The LOGMODE parameter and the GNAME parameter are mutually exclusive.

LOGMODE=logon_mode_name

The LOGMODE field in an NIB is used by the INQUIRE OPTCD=SESSPARM, OPNDST, REQSESS, CLSDST OPTCD=PASS, and SIMLOGON macroinstructions to indirectly specify a set of session parameters. See NIB LOGMODE and BNDAREA operands for details.

LOGMODE=0

must be specified, explicitly or by default, in the NIB used to give a CNM application program access to the SSCP-LU session.

LUAFFIN

Indicates a specific affinity ownership condition between the application and a specific partner LU for the session that is being started by the OPNDST or OPNSEC macroinstruction. The LUAFFIN parameter is mutually exclusive with the AFFIN parameter.

LUAFFIN=NOTAPPL

Indicates that VTAM is to be the owner of the affinity for a specific LU on the OPNDST or OPNSEC macroinstruction. This option is not honored if a session already exists with this LU, with the application already established as the owner of the affinity.

LUAFFIN=APPL

Indicates that the application program is to be the owner of the affinity for a specific LU on the OPNDST or OPNSEC macroinstruction. This option is not honored if a session already exists with this LU, with VTAM already established as the owner of the affinity.

MODE=RECORD

This operand is allowed by VTAM for migration purposes.

MODE=RECORD is optional and can only be specified if NETID is not specified on the NIB macroinstruction. MODE=RECORD is not valid when NETID is specified on the NIB macroinstuction.

MTSAREA=MTS_area_address

Specifies the address of an area containing MTS override data. This data is required when you specify OPTCD=MTS on a REQSESS or CLSDST PASS macroinstruction. You must format the specified area to match the ISTMTS DSECT. For additional information about the ISTMTS DSECT, see Control block formats and DSECTs.

Note: MTSAREA and BNDAREA are mutually exclusive keywords on this macroinstruction. The MTSAREA keyword is an alternate name for the BNDAREA keyword. The NIBMTSAR field set by the MTSAREA keyword is an overlay of the NIBNDAR field set by the BNDAREA keyword.

NAME=session_parameter_name

Associates the NIB with its session parameter.

Example:

NAME=LU13

Although this operand is sometimes optional, the NAME field generally should be set by the time a CLSDST, OPNDST, SIMLOGON, INTRPRET, REQSESS, TERMSESS, SESSIONC, OPNSEC, or INQUIRE or SETLOGON OPTCD=GNAMESUB macroinstruction is issued that uses this NIB. When OPNDST OPTCD=(ACCEPT,ANY) is issued, the NAME field need not be set, because VTAM places the name of the LU in this field. See the individual macroinstruction descriptions to determine whether alternatively the RPLARG or whether the NIBCID field is used.

If you omit this operand, the entire 8-byte NAME field is set to EBCDIC blanks.

This operand must be omitted in the NIB used by a CNM application program to gain access to the SSCP-LU session.

If this application uses NQNAMES=YES, this name is used with the NETID operand.

If this application uses NQNAMES=NO and NETID is not specified, VTAM will use the first located instance of the name provided associated with the application program.

If CHANGE OPTCD=ENDAFFIN|ENDAFFNF is issued using this NIB, you can specify NAME=* to end all affinities associated with the issuing application program. This function is intended for use by an application only immediately prior to closing its ACB.

When issuing SETLOGON OPTCD=GNAMESUB, this operand should be set to the application program network name of the generic resource instance specified in the VTAM node identification block (NIB).

Note: The NAME parameter and PROC=STOKEN are mutually exclusive.

NETID=network_identifier

Specifies an optional 1–8 character network name, (padded with blanks), that identifies the network in which the partner LU, identified by the NAME operand, resides. If you do not code NETID, no network identifier is associated with this application program. The value for NETID is stored in the NIBNET field in ISTDNIB.

The NETID operand and the MODE operand are mutually exclusive.

PROC=processing_option

Indicates options that VTAM is to follow for subsequent RPL-based requests involving the session established by an OPEN (for a CNM application program), OPNDST, SETLOGON, or OPNSEC using this NIB.

Format: Code as indicated in the preceding assembler format table. The parentheses can be omitted if only one option code is selected:

NIB   NAME=LU3,NETID=NETA,PROC=(DFASYX,RESPX,CONFTXT)

The following describes each of the possible parameters for PROC.

PROC=CA

CA, CS, and RPLC apply for a session when input received from that session satisfies a RECEIVE. These PROC options override the CS and CA option codes that might have been specified in the RECEIVE macroinstruction or the RPL referred to by the RECEIVE macroinstruction, but not the CS and CA option of any other type of macroinstruction.

With PROC option CA, the session should be put into continue-any mode after this RECEIVE is completed for the type of input that satisfies the RECEIVE. It can be used as long as a session responds to a RECEIVE OPTCD=ANY macroinstruction. This might be the case if the session normally sends no more than one request per transaction.

PROC=CS

The session should be put into continue-specific mode after this RECEIVE is completed for the type of input that satisfies the RECEIVE. It can be used when a session is to be prevented from completing any subsequent RECEIVE OPTCD=ANY macroinstructions. This might be the case if the session normally sends multiple requests per transaction.

PROC=CONDCS

The session should be put into continue-specific mode after this RECEIVE OPTCD=ANY is completed for the type of input that satisfies the RECEIVE only if more input data remains. More input data is considered to be remaining if RECLEN > AREALEN and KEEP was indicated (see PROC=KEEP). If no input data remains, the session is to be prevented from completing any subsequent RECEIVE OPTCD=ANY macroinstructions for the remaining data. This might be the case if the session normally sends multiple requests per transaction and all the input data can normally be contained in the RECEIVE's buffer. Specifying this options can allow the application the application to avoid the overhead of a RESETSR macroinstruction after every RECEIVE OPTCD=ANY.

In order to ensure that the application receives the input data in the correct order, EXIT should be specified on the RECEIVE. Also note that if a session does send in multiple requests per transaction, a single session can use up a greater number of RECEIVE OPTCD=ANY macros. Consequently, an application that utilizes this function may want to increase the number of RECEIVE OPTCD=ANY macros it has outstanding.

PROC=RPLC

The CS, CA or CONDCS option code in the RECEIVE macroinstruction or the RPL referred to the RECEIVE macroinstruction should be used when switching continue modes.

PROC=KEEP

VTAM fills the input data area and saves any remaining data for subsequent RECEIVE macroinstructions.

PROC=TRUNC

VTAM fills the input data area and discards any remaining data. No error condition is indicated.

The presence of excess data can be determined by comparing the RPL's AREALEN field (input area size) with the RECLEN field (amount of incoming data). If the value in RECLEN exceeds the value in AREALEN, excess data has been kept (and is used to satisfy the next appropriate RECEIVE). An example is shown in Handling overlength input data.

The NIB's TRUNC-KEEP processing option is effective only if the NIBTK option code is set in the RPL. If the KEEP or TRUNC option codes are set in the RPL, then the NIB's TRUNC-KEEP processing option is overridden.

PROC=CONFTXT

The buffers used to hold data are cleared before they are returned to their buffer pools. The data is considered as "confidential".

PROC=NCONFTXT

The buffers used to hold data are not cleared before they are returned to their buffer pools.

PROC=DFASYX

When DFASYX is set for the sessions' NIB and no other restrictions prevent the scheduling of the ACB-oriented DFASY exit-routine, the exit routine is scheduled. If the exit routine cannot be scheduled or the session is established with PROC=DFASYX, a RECEIVE OPTCD=ANY, RTYPE=DFASY is not valid. See Figure 2 for more information about the DFASY exit routine.

PROC=NDFASYX

The DFASY exit routine is not scheduled.

PROC=NEGBIND

When a PLU application program specifies NEGBIND in an OPNDST macroinstruction, VTAM sends a negotiable BIND request to the SLU.

PROC=NNEGBIND

When a PLU application program specifies NNEGBIND in an OPNDST macroinstruction, VTAM sends non-negotiable BIND request.

When an SLU application program receives a negotiable BIND request in its SCIP exit routine, the session parameters can be checked to determine if the suggested parameters are agreeable. If the application program agrees with the session parameters sent by the PLU, the application program issues an OPNSEC macroinstruction that refers to an NIB with NNEGBIND specified, or with NEGBIND specified and BNDAREA=0. If the application program wants to suggest new session parameters, it issues an OPNSEC macroinstruction with the NIB specifying NEGBIND and BNDAREA containing the address of the new session parameters.

If a list of OPNDST OPTCD=ACQUIRE is used, only one of the NIBs in the list can specify PROC=NEGBIND.

PROC=RESPX

When RESPX is set for the sessions' NIB and no other restrictions prevent the scheduling of the ACB-oriented RESP exit routine, the exit routine is scheduled. If the exit routine cannot be scheduled or the session is established with PROC=RESPX, a RECEIVE OPTCD=ANY, RTYPE=RESP is not valid. See Figure 3 for more information about the RESP exit routine.

PROC=NRESPX

The RESP exit routine is not scheduled.

PROC=ORDRESP

PROC=NORDRESP

Indicate whether certain designated normal-flow responses are to be handled by VTAM in a manner similar to the handling of normal-flow (DFSYN) requests. The ORDRESP and NORDRESP options are used in conjunction with the QRESP and NQRESP options in the RPL. For SEND of normal-flow data-flow-control requests, this operand also controls whether the POST and RESPOND fields are examined. Refer to Controlling the handling of normal-flow responses for details.

PROC=APPLRESP

The application program must respond to the expedited-flow data-flow-control request using a SEND STYPE=RESP macroinstruction. While either a positive or negative response can be sent, a definite response type 1 (FME) must be used in either case. The sequence number and request code (CONTROL) used in the response can be obtained from the RECEIVE RPL or the VTAM read-only RPL supplied in the application exit routine.

For XRF only, during a session takeover, VTAM does not provide reasons for expedited flow requests to the failed active subsystem. The alternate application is responsible for providing these responses, and PROC=APPLRESP must be coded for all XRF sessions.

PROC=STOKEN

specifies that, for SETLOGON OPTCD=GNAMEADD processing, VTAM is to pass the value of the NIBSTKN field in ISTDNIB to the operating system for generic resource workload balancing. Be sure that NIBSTKN is set when specifying PROC=STOKEN.

When specified, the PROSTOKN indicator will be set on in the generated NIB.

Note: The NAME parameter and PROC=STOKEN are mutually exclusive.

PROC=SYSRESP

VTAM responds to the request.

RESPLIM=response_limit

Indicates the maximum number of responded output requests that can be pending at one time for a session. (A responded output request is a SEND POST=RESP, STYPE=REQ, and CONTROL specifying data or a normal-flow data-flow-control request.) If RESPLIM=0 is coded, VTAM imposes no limit on the number of pending responded output requests. The maximum value that can be coded is decimal 65535. RESPLIM=1 is the default.

SDT

For an application program acting as the primary end of a session, this operand indicates whether the application program or VTAM is to send the first SDT request on the session.

For an application program acting as the secondary end of a session, this operand when coded for an OPNSEC macroinstruction indicates whether the application program or VTAM responds to an SDT request (by issuing SESSIONC CONTROL=SDT, STYPE=RESP).

The use of this operand is determined by the transmission services profile specified in the session parameters used for the session (see Specifying a session parameter). The operand is ignored if the transmission services profile does not include SDT.

For the NIB used to give a CNM application program access to the SSCP-LU session, SDT=SYSTEM must be specified, explicitly or by default.

SDT=SYSTEM

VTAM automatically sends an SDT request as part of the session-establishment process before posting the OPNDST RPL complete.

SDT=APPL

VTAM does not send an SDT request until the application program tells it to do so (by issuing SESSIONC CONTROL=SDT,STYPE=REQ).

USERFLD=user_data

Indicates any 4 bytes of data that the application program wants to associate with a session-initiation request, or with the session itself.

The USERFLD in the NIB associated with a SIMLOGON, REQSESS, or CLSDST OPTCD=PASS is retained by VTAM and is subsequently returned to the application program that issued the session-initiation request in the exit parameter list for the LOGON exit routine (for SIMLOGON), SCIP exit routine (for REQSESS), or NSEXIT exit routine (for SIMLOGON, REQSESS, or CLSDST OPTCD=PASS). Refer to Exit routines related to session establishment and termination.

The USERFLD in the NIB associated with an OPEN (for a CNM application program), OPNDST, or OPNSEC macroinstruction is saved by VTAM for the session established by one of these macroinstructions and is returned in the RPL USER field whenever an RPL-based operation (for example, RECEIVE) completes for that session or an exit routine (for example, RESP) is entered for that session.

Note: The USERFLD associated with an OPNDST or OPNSEC macroinstruction overrides that field specified in a SIMLOGON or REQSESS macroinstruction. Thus, if the same 4 bytes of user data are to be saved by VTAM for the session as were saved for the session-initiation request, the OPNDST or OPNSEC macroinstruction must specify the same value originally specified in the corresponding SIMLOGON or REQSESS macroinstruction.

Format: Code the 4 bytes of data in either character, fixed-point, or hexadecimal format, or, if an address is desired, code it as an A-type or V-type address constant. Register notation cannot be used.

Example:

USERFLD=C'LU01'
USERFLD=F'100'
USERFLD=00043E0
USERFLD=A(RTN1)
USERFLD=V(EXTRTN)

If you omit this operand, the USERFLD field is set to 0.