Parameters for REQUEST=CONNECTION

,ACCESS=UPDATE

,ACCESS=READ

When REQTYPE=CREATE is specified, use this optional parameter to indicate what type of access the indicated connection is to enjoy. The default is ACCESS=UPDATE.

,ACCESS=UPDATE: The connection can create, write, replace, read, or delete notes in the note pad.
The calling program must have SAF authorization that permits UPDATE access to the FACILITY class resource IXCNOTE.owner.application. If SAF is not available, or if there is no IXCNOTE.owner.application resource defined for the note pad in the FACILITY class, a program running in supervisor state or with a PKM allowing key 0-7 is permitted to create a connection.
,ACCESS=READ: The connection can read notes in the note pad, but it cannot create, write, replace, or delete notes.
The calling program must have SAF authorization that permits READ access to the FACILITY class resource IXCNOTE.owner.application. If SAF is not available, or if there is no IXCNOTE.owner.application resource defined for the note pad in the FACILITY class, a program running in supervisor state or with a PKM allowing key 0-7 is permitted to create a connection.

,CONNECTION=connection

Use this required input/output parameter to specify a storage area. A token for the subject connection will either be fetched from or stored into this area.

For REQTYPE=CREATE, CONNECTION is an output variable and a token representing the connection will be stored in the indicated area. This token must be passed on subsequent IXCNOTE requests that manipulate the connection or access notes in the note pad. Note that the requester must carefully preserve the CONNECTION token because this is the only opportunity to acquire the token. XCF does not make the token available via any other service or IXCNOTE request.

For all other REQTYPE specifications, CONNECTION is an input variable and a token will be fetched from the indicated storage area. The token identifies the connection that is to be processed. The token would have been returned by a prior IXCNOTE request that was issued to create the connection on the local system.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32 character field.

,DESCRIPTION=description

When REQTYPE=CREATE is specified, use this required input parameter to specify a variable containing a description of the connector. The description might indicate the function, service, purpose, or role of the connector. Or it might indicate the application with which the connector is associated. The string can contain any alphanumeric (a-z, A-Z, 0-9), national (@, #, $), or special (underscore or blank) character. Leading blanks and all blank descriptors are not permitted. Descriptions are case sensitive. XCF presents the connector description when providing information about the connection. The description also appears in various XCF messages and diagnostic data reports. The intended purpose is to help installations and service personnel understand how the system (or sysplex) might be impacted if there are problems with this connector or its use of the note pad.

The storage containing the DESCRIPTION must reside in the primary address space of the caller, or in a space addressable via a public entry on the Dispatchable Unit Access List (DU-AL), or in a common area data space. The storage must be accessible using the PSW key of the program making the request.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32 character field.

,INFO=info

,INFO=0

When REQTYPE=CREATE is specified, use this optional input parameter to specify a variable which contains information about the connector. The content and interpretation of this information is determined by the creator of the connection. XCF associates a copy of the indicated data with the connector. The connector might, for example, use INFO to document the protocols that it supports.

The storage containing the INFO must reside in the primary address space of the caller, or in a space addressable via a public entry on the Dispatchable Unit Access List (DU-AL), or in a common area data space. The storage must be accessible using the PSW key of the program making the request.

The default is 0.

To code: Specify the RS-type address, or address in register (2)-(12), of a 64-character field.

,NOTEPAD=notepad

When REQTYPE=CREATE is specified, use this required input parameter to specify a variable containing the name of an existing note pad to which a connection is to be created.

Note pad names are mapped by IXCYNOTE_TNOTEPADNAME. Note pad names consist of four 8 byte sections. The various sections identify the owner of the note pad, the application using the note pad, and its function. Each 8 byte section must be left justified, padded on the right with EBCDIC blanks as needed. Each section can contain any uppercase alphabetic (A-Z), numeric (0-9), national (@, #, $), or underscore (_) character.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32 character field.

,REQTYPE=CREATE

,REQTYPE=DELETE

,REQTYPE=PAUSE

,REQTYPE=RESUME

Use this required parameter to indicate the type of request to be processed for the connection.

,REQTYPE=CREATE

Create a connection to the note pad.

,REQTYPE=DELETE

Delete the connection to the note pad.

If there is no further need for the note pad, one should explicitly delete the note pad (by issuing IXCNOTE REQUEST=NOTEPAD REQTYPE=DELETE) so that system resources can be released in a timely manner.

A DELETE request can be issued by a work unit that can satisfy any of the following conditions:

Requester is the connector
Home is connector address space and the requester has SAF authorization appropriate for the ACCESS specified by the creator of the connection
Running in supervisor state or with a PKM allowing key 0-7 and either:
- The creator of the connection specified USAGE=SERVER and primary is the connector address space, or
- The creator of the connection specified USAGE=CLIENT

,REQTYPE=PAUSE

Wait for a condition to clear. The service routine is to suspend the caller until the relevant condition is resolved, or it is determined that the condition cannot be resolved. The service routine will also return when the indicated TIMEOUT value expires. The service routine might also return if the state of any relevant condition changes.

For example, a prior IXCNOTE request might have been rejected with a return and reason code indicating that the note pad is quiesced. While quiesced, all attempts to access notes in the note pad will be rejected. The connector can use REQTYPE=PAUSE to determine when typical note activity can be resumed.

A connection could be quiesced as the result of several different conditions occurring simultaneously. While paused, there could be a change in the set of quiesce conditions. Some conditions might clear, while new ones might occur. The service routine always returns to the caller when the set of quiesce conditions clears and the note pad is once again accessible. The service routine might also return to the caller when the set of quiesce conditions changes, even though the connection remains quiesced.

The paused unit of work will also be resumed if the connection is deleted or if the note pad fails. Note that "connection is deleted" includes the case where the connection is deleted due to termination of the TERMSCOPE entity, in which case the paused unit of work will be resumed if the work unit is still viable. One can also resume the work unit by invoking IXCNOTE to process a REQTYPE=RESUME request (from some other unit of work).

The return and reason code presented to the caller of the PAUSE request indicate whether the note pad is accessible upon return from the PAUSE. Return code 0 implies that the connection no longer has any conditions that would preclude typical use. Return code 4 is used when the connection still has conditions for which a PAUSE might be appropriate. Return code 8 is used if the connection no longer exists.

Thus upon return from the service routine, the connection might still be quiesced. The connector can elect to reissue the PAUSE in order to continue waiting for the connection to become unquiesced, or it might take some other relevant recovery action according to the specific quiesce conditions that remain.

For a given connection, at most one unit of work can be paused for a REQTYPE=PAUSE request.

A PAUSE request can be issued by a work unit that can satisfy any of the following conditions:

Requester is the connector
Home address space is the connector address space
Primary address space is the connector address space
Running in supervisor state or a PKM allowing key 0-7

If an answer area is provided (ANSAREA), information related to the pause conditions is stored in the field AA_DETAILS when the request completes with return code 0 or 4. The details are mapped by IXCYNOTE_TDETAILSRESUMED.

,REQTYPE=RESUME

Resume the work unit that is currently paused for the indicated connection. Use this service to release a paused connection (REQTYPE=PAUSE) before the quiescing conditions clear or before the connection is deleted.

If a work unit is currently paused for the connection, the suspended work unit will be resumed and the PAUSE request will return to its caller. If a work unit is not currently paused for the connection, the next PAUSE request to be accepted will be resumed immediately.

A RESUME request can be issued by a work unit that can satisfy any of the following conditions:

Requester is the connector
Home address space is the connector address space
Primary address space is the connector address space
Running in supervisor state or a PKM allowing key 0-7

,TERMSCOPE=TASK

,TERMSCOPE=HOME

,TERMSCOPE=PRIMARY

When REQTYPE=CREATE is specified, use this required parameter to indicate an entity with which the connection is to be associated for the purposes of termination processing. If the indicated entity terminates, XCF deletes the connection. Note that a connection is always deleted when the local system terminates, or when the connector address space terminates. For a connection with task scope (TCBSENV is nonzero), the connection is always deleted if the connector task terminates.

The TERMSCOPE keyword enables the creator of the connection to bind the existence of the connection to a designated task or space. A connection cannot be associated with a task or address space that is in the midst of being (or has already) terminated.

,TERMSCOPE=TASK: The connection is to be terminated when the indicated task or the address space in which it resides terminates.
,TERMSCOPE=HOME: The connection is terminated when the home address space of the caller terminates.
To be precise, the connection will be deleted when the task that owns the cross-memory resources in the home address space terminates. The Task Control Block (macro IKJTCB) for that task is anchored in the ASCBXTCB field of the Address Space Control Block (macro IHAASCB) for the address space.
,TERMSCOPE=PRIMARY: The connection is terminated when the primary address space of the caller terminates.
To be precise, the connection will be deleted when the task that owns the cross-memory resources in the primary address space terminates. The Task Control Block (macro IKJTCB) for that task is anchored in the ASCBXTCB field of the Address Space Control Block (macro IHAASCB) for the address space.

,TIMEOUT=timeout

,TIMEOUT=XCF

Use this optional input parameter to indicate the number of seconds that the caller is willing to allow for the request to complete. The TIMEOUT specification imposes an upper bound on the duration of the request.

If the TIMEOUT keyword is not specified, or if TIMEOUT=XCF is specified, or if the specified value is zero, the amount of time allotted to allow for the request to complete is at the discretion of XCF.

The amount of time needed to complete a given REQTYPE will depend on the nature of the request as well as the state of the system and the note pad. In particular, there is the potential for any given request to be delayed while XCF processes previously accepted requests, some of which could be long running.

For REQTYPE=PAUSE, note that many quiescing conditions are not likely to be resolved for several minutes. In some cases, manual intervention can be required to resolve the problem.

Choose TIMEOUT values accordingly.

For a REQTYPE other than PAUSE, the request is processed asynchronously. If the request times out, XCF will not be able to provide the results of the request. However, the request might or might not have been processed successfully. Depending on the request and the design of the exploiting application, it might be appropriate to try the request again, perhaps with a longer timeout value. If a REQTYPE=CREATE request times out, XCF will make sure that the connection does not exist before returning.

The default is XCF.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,TTOKEN=ttoken

,TTOKEN=CURRENT

When TERMSCOPE=TASK and REQTYPE=CREATE are specified, use this optional input parameter to contain the task token of the relevant task. The TCBTOKEN macro is typically used to obtain task tokens.

If TTOKEN=CURRENT is specified or taken as the default, or if the content of the TTOKEN variable is hexadecimal zero, the system uses the task token of the current task. SRB mode callers must explicitly pass a nonzero TTOKEN.

For a program running in problem state with a PKM allowing key 8-15, the TTOKEN must represent a task that resides in the home address space. The specified task must be the job step program task or a descendent thereof. The specified task must also be the current task or an ancestor thereof.

For a program running in supervisor state or with a PKM allowing key 0-7, the TTOKEN must represent a task that resides in either the home address space or the primary address space of the caller. The default is CURRENT.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,USAGE=CONNECTOR

,USAGE=SERVER

,USAGE=CLIENT

When REQTYPE=CREATE is specified, use this optional parameter to specify the intended use of the connection. When the connection is subsequently used to process notes in the note pad (REQUEST=NOTE or REQUEST=NOTES), USAGE determines the conditions under which the requester is deemed to be a valid user.

To specify USAGE=SERVER or USAGE=CLIENT, the creator of the connection must be running in supervisor state or with a PKM allowing key 0-7, and the primary address space must be the home address space. In addition, for USAGE=SERVER, a task mode caller must not have a task specific security environment (TCBSENV must be zero).

The default is USAGE=CONNECTOR.

,USAGE=CONNECTOR

The connection is to be used by work units running out of the connector address space.

When processing notes, a work unit is deemed to be a valid user of the connection if it can satisfy any of the following conditions:

Requester is the connector
Home is connector space and user has SAF authorization appropriate for the REQTYPE
Supervisor state or PKM allowing key 0-7, and running as an address space resource manager

,USAGE=SERVER

The connection is to be used by a server that processes notes while running in its own address space.

When processing notes, a work unit is deemed to be a valid user of the connection if it can satisfy any of the following conditions:

Requester is the connector
Home is connector space and user has SAF authorization appropriate for the REQTYPE
Supervisor state or PKM allowing key 0-7, and running as an address space resource manager
Primary is connector space, and requester is supervisor state or PKM allowing key 0-7¹

USAGE=SERVER is typically used in a client/server application where a client running in an arbitrary address space calls the server to perform some service that executes while running in the server address space. The server address space creates the note pad connection for its own internal use. Since the client is neither the connector nor running out of the connector address space, XCF would typically deny the server request to access its own note pad from the client thread. With the SERVER option, XCF allows the client work unit to access the note pad if the server (connector) address space is primary at the time of the request, and the program is running supervisor state or with a PKM allowing key 0-7.

,USAGE=CLIENT

The connection is to be used by a server that processes notes while running in the client address space.

When processing notes, a work unit is deemed to be a valid user of the connection if it can satisfy any of the following conditions:

Requester is the connector
Home is connector space and user has SAF authorization appropriate for the REQTYPE
Supervisor state or PKM allowing key 0-7, and running as an address space resource manager
Requester is supervisor state or PKM allowing key 0-7¹

USAGE=CLIENT is typically used in a client/server application where a client running in an arbitrary address space calls the server to perform some service that executes while running in the client address space. The server address space creates the note pad connection for its own internal use. Since the client is neither the connector nor running out of the connector address space, XCF would typically deny the server request to access its own note pad from the client thread. With the CLIENT option, XCF allows the client work unit to access the note pad, provided the program is running supervisor state or with a PKM allowing key 0 to 7.