IXGCONN — Connect/disconnect to log stream

The requirements for the caller are:

• The parameter list for this service must be addressable in the caller's primary address space.
• Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
• Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the ANSAREA parameter.
• If you use IXGCONN REQUEST=CONNECT,...,MF=(E,parmlist,NOCHECK) with either the STREAMTOKEN=xxxx or the USERDATA=yyyy keyword, the following procedure must be followed. When the processing is complete, move the STREAMTOKEN or USERDATA values from the parameter list specified on MF= to your own storage.
• Each task that issues IXGCONN REQUEST=CONNECT to connect to a log stream must later issue IXGCONN REQUEST=DISCONNECT to disconnect from the log stream. When a task disconnects from the log stream, the log stream token that identified the connection expires. Any requests that use the log stream token after the disconnect are rejected with reason code X'82D'.
• If a task that issued the IXGCONN REQUEST=CONNECT request ends before issuing a disconnect request, system logger automatically disconnects the task from the log stream. This means that the unique log stream connection identifier, or the STREAMTOKEN, is no longer valid. The application receives an expired log stream token error response with reason code X'82D', if this application continues to use the same STREAMTOKEN after the task has been disconnected on subsequent logger service requests.
• Any job step task (JST) terminates within the address space that has a connection to the log stream. System logger treats any job step task termination in a manner similar to an address space termination. That is, all log stream connections are disconnected and logger associations are terminated with the address space.

  If this condition occurs and there remains an expected use of a log stream, then a new log stream connection will be required.

• All storage areas specified in this service must be in the same storage key as the caller's storage key and must exist in the caller's primary address space.
• The caller cannot have an EUT FRR established.
• If the System Authorization Facility (SAF) is available, the system performs SAF authorization checks on all IXGCONN REQUEST=CONNECT requests in order to protect the integrity of data in a log stream.
  To connect successfully to a log stream, the caller must have SAF authorization that matches the authorization required for the log stream:

  • To connect to a log stream with an authorization level of READ, the caller must have read (or higher level) access to RESOURCE(log_stream_name) in SAF class CLASS(LOGSTRM).
  • To connect to a log stream with an authorization level of WRITE, profiles covering two separate resources are used to determine if access is allowed and whether full access to log stream services can be used or just limited log stream access (only IXGWRITE and disconnect requests) can be used for the connection. Refer to each log stream exploiter's planning and/or guidance documentation on their log stream access requirements. Grant permission to SAF profile covering the (WRITE_ONLY_log-stream-name) resource only when deemed appropriate for the log exploiter.
    • For full service WRITE log stream access, the caller must have update (or higher level) access to RESOURCE(log_stream_name) in SAF class CLASS(LOGSTRM). When this level of access is granted, all log stream access services can be used with the log stream token established on this log stream connection.
    • For limited service WRITE log stream access, the caller must have (at least) update access to RESOURCE(WRITE_ONLY_log-stream-name) in SAF CLASS(LOGSTRM). When this level of access is granted, only IXGWRITE and IXGCONN (to disconnect) requests can be used with the log stream token established on this log stream connection.
    • When there are no profiles defined covering resources (log-stream-name) or (WRITE_ONLY_log-stream-name) in SAF CLASS(LOGSTRM), then the AUTH=WRITE connection is permitted as full service access to the log stream.
    • When just the profile covering resource (log-stream-name) is defined, meaning no profile covering (WRITE_ONLY_log-stream-name), then the connection is permitted according to the (log-stream-name) profile access. Access to the log stream will either be full service access or connection is not allowed (denied).
    • When just the profile covering resource (WRITE_ONLY_log-stream-name) is defined, meaning no profile covering (log-stream-name), then the connection is permitted based on the (WRITE_ONLY_log-steram-name) profile access. Access to the log stream will either be limited service log stream access (can only write log data and disconnect) or the connection is not allowed (denied).
    • When profiles covering both resources (WRITE_ONLY_log-stream-name) and (log-stream-name) are defined, then connection is permitted based on the following combinations:
      • when access is permitted via both profiles, then access to the log stream will be full service access.
      • when access is permitted via (log-stream-name) profile, but is denied via (WRITE_ONLY_log-stream-name) profile, then access to the log stream will be full service access.
      • when access is permitted via (WRITE_ONLY_log-stream-name) profile, but is denied via (log-stream-name) profile, then access to the log stream will be limited service (can only write log data and disconnect).
      • when access is not permitted (denied) via both profiles, then the connection to the log stream will not be allowed (denied).

      When permission is not allowed for the profiles covering the resources noted above, system logger will provide an error return, with return code 8, reason code X'080D' (lxgRsnCodeNoSAFAuth) on the log stream connection attempt.

    

  If SAF is not available or if CLASS(LOGSTRM) is not defined to SAF, no security checking is performed. In that case, the caller is connected to the log stream with the requested or default AUTH parameter value.

• There is more than one version of this macro available. The parameters you can use depend on the version you specify on the PLISTVER parameter. See the description of the PLISTVER parameter for more information.

Before issuing the IXGCONN macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

The standard form of the IXGCONN macro is written as follows:

The parameters are explained as follows:

REQUEST=CONNECT

REQUEST=DISCONNECT

Input parameter specifying whether the program is connecting to or disconnecting from the specified log stream.

When you specify CONNECT, all parameters are valid. Keywords required with connect are: STREAMNAME, STREAMTOKEN, ANSAREA, and ANSLEN.

When you specify DISCONNECT, the following parameters are valid (required parameters are underlined): STREAMTOKEN, ANSAREA, ANSLEN, USERDATA, RETCODE, RSNCODE, and MF.

,STREAMNAME=streamname

Specifies the 26-byte field (or register) containing the name of the log stream to which a program is connecting. You must use the name you defined for the log stream in the LOGR, LOGRY or LOGRZ couple data set policy that is active on the system where the log stream is being connected. See the IXGINVNT macro for information on the syntax of log stream names in the active system logger policy.

,STREAMTOKEN=streamtoken

Specifies the 16-byte token uniquely identifying the program's connection to the log stream.

When specified with REQUEST=CONNECT, STREAMTOKEN is an output parameter where IXGCONN places the log stream token when the macro completes successfully.

When specified with REQUEST=DISCONNECT or other logger services, STREAMTOKEN is an input parameter where you specify the log stream token returned at connection.

,ANSAREA=ansarea

Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.

,ANSLEN=anslen

Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.

To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.

,AUTH=READ

,AUTH=WRITE

Specifies whether the caller has write or read access to the specified log stream.

If you specify AUTH=READ when connecting to a log stream, the program must also have read access authority to SAF resource(logstream_name) in CLASS(LOGSTRM) for the specified log stream. You can then issue only the IXGBRWSE and IXGQUERY requests against the log stream.

If you specify AUTH=WRITE when connecting to a log stream, the program must also have write access authority to SAF resource(logstream_name) in CLASS(LOGSTRM) for the specified log stream. You can then issue any system logger request against the log stream.

AUTH=WRITE specifies that, based on the defined security profiles and allowed access, either all log stream access services (such as IXGBRWSE, IXGDELET, IXGWRITE and others) or just limited log stream access requests (just writing log data and disconnecting from the log stream) can be issued for the log stream.

When the request results in a log stream connection (rc=0 or rc=4 conditions), then the output answer area flag field Ansaa_WriteConnectLimitedAccess (see mapping macro IxgAnsaa) indicates whether full log stream access services are allowed or whether only limited log stream service access is allowed.

When the indicator Ansaa_WriteConnectLimitedAccess is set off '0'b then full log stream access services area is allowed. This means that all the log stream access services using the log stream connection token returned in the STREAMTOKEN parameter and that are given the context of the other connection parameters, can be issued.

When the indicator Ansaa_WriteConnectLimitedAccess is set on '1'b along with indicator Ansaa_WriteOnlyAccess being set on '1'b, then the log stream access services area limited to writing log data and disconnecting from the log stream (IXGWRITE and IXGCONN requests). No other log stream access services are allowed for this limited access connection type

,STRUCTNAME=structname

Specifies the name or address (using a register) of a 16-byte output field where IXGCONN REQUEST=CONNECT will return the name of the coupling facility structure that the log stream is connected to. The name comes from the LOGR policy.

If you are connecting to a DASD-only log stream, this field will contain binary zeros. In addition, flag Ansaa_DasdOnlyLogStream in macro IXGANSAA will be set on for a DASD-only log stream.

,MAXBUFSIZE=maxbufsize

Specifies the name or address (using a register) of a 4-byte output field where IXGCONN returns the size, in bytes, of the largest log block that can be written to this log stream.

MAXBUFSIZE is defined in the active system logger couple data set policy.

,AVGBUFSIZE=avgbufsize

Specifies the name or address (using a register) of a 4-byte output field where IXGCONN returns the average size, in bytes, of individual log blocks that can be written to the coupling facility structure associated with this log stream.

AVGBUFSIZE is defined in the active system logger couple data set policy.

• If you are using an active system logger couple data set for a coupling facility log stream, this value shows the initial setting used to determine the element-to-entry ratio. System logger monitors structure usage and adjusts the average buffer size dynamically, but the AVGBUFSIZE value returned by IXGCONN will always reflect the original setting rather than the actual value in use by system logger at any given time.
• If you are connecting to a DASD-only log stream, this field will contain binary zeros. In addition, flag Ansaa_DasdOnlyLogStream in macro IXGANSAA will be set on for a DASD-only log stream.

,ELEMENTSIZE=elementsize

Specifies the name or address (using a register) of a 4-byte output field where IXGCONN returns the size of the elements that system logger will break the log blocks into to write them to the coupling facility associated with this log stream.

If you are connecting to a DASD-only log stream, this field will contain binary zeros. In addition, flag Ansaa_DasdOnlyLogStream in macro IXGANSAA will be set on for a DASD-only log stream.

,LSVERSION=lsversion

Specifies the name or address (using a register) of a 64-bit output field where IXGCONN returns the version of the log stream the program is connecting to.

The log stream version is a UTC timestamp that uniquely identifies the instance of the log stream definition. A program can use the log stream version to see if a log stream definition has been deleted and redefined since the last connect to a log stream.

For example, assume you connect to log stream LS1 and IXGCONN returns a log steam version of X'AA00000000000000', which the program saves. On a subsequent connection to log stream LS1, IXGCONN returns a different log stream version, which indicates that the definition for log stream LS1 in the active system logger couple data set policy has been deleted and redefined since the last connection.

,USERDATA=userdata

Specifies a 64-byte input/output field containing a user data area.

When specified with REQUEST=CONNECT, USERDATA is an output parameter where IXGCONN returns the user data specified for this log stream.

When specified with REQUEST=DISCONNECT, USERDATA is an input parameter where you can specify or update the user data the user data for the specified log stream. You can only specify or change the user data for a log stream on a disconnect request.

,IMPORTCONNECT=NO

,IMPORTCONNECT=YES

Specifies whether the connection is for writing or importing log data to a log stream. You must specify AUTH=WRITE to use the IMPORTCONNECT parameter.

If you specify IMPORTCONNECT=YES, this connection will be used for importing data to a log stream. Importing log data means using the IXGIMPRT service to copy data from one log stream to another, maintaining the same log block identifier and UTC time stamp. IXGWRITE requests are not valid with IMPORTCONNECT=YES. You can have only one IMPORTCONNECT=YES connection active for a log stream in the sysplex.

If you specify IMPORTCONNECT=NO, which is the default, the connect request is a write connection. In a write connection, only IXGWRITE requests can be issued against the log stream, IXGIMPRT requests will be rejected.

You can have multiple write connects to a log stream, provided there are no import connections. If you have a write connect established against a log stream, a subsequent import connection will be rejected. You cannot, in other words, issue both IXGIMPRT and IXGWRITE requests against a single log stream.

This option is not allowed when the AUTH=WRITE connection would have otherwise been established as a limited log stream access, given the SAF profiles defined for the log stream access. The request will fail with a return code 8, reason code X'08D6' (IxgRsnCodeConnTypeNotAllowed). The answer area indicators Ansaa_WriteConnectLimitedAccess and Ansaa_WriteOnlyAccess will be set on ('1'b) for this error condition.

,DIAG=NO_DIAG

,DIAG=NO

,DIAG=YES

Specifies whether Logger should provide additional diagnostics as specified on the logstream definition DIAG parameter. This indication is used over the span of this connectoin. Refer to the DIAG keyword on the IXGINVNT, IXGBRWSE, and IXGDELET macro services.

If you specify DIAG=NO_DIAG, which is the default, then Logger will not provide the additional diagnostics as specified on the logstream definition DIAG parameter, unless another Logger service, for example, IXGBRWSE, specifically requests the additional diagnostics.

If you specify DIAG=NO, the Logger will not provide the additional diagnostics as specified on the logstream definition DIAG parameter, regardless of other Logger service specifications.

If you specify DIAG=YES, then Logger will provide additional diagnostics as specified on the logstream definition DIAG parameter, unless another Logger service, for example, IXGDELET, specifically requests not to provide the additional diagnostics.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=1

,PLISTVER=2

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.

The values are:

• IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
• MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.

  If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

• 1, which supports all parameters except those specifically referenced in higher versions.
• 2, which supports both the following parameters and parameters from version 1:
  • IMPORTCONNECT
  • LSVERSION

To code: specify in this input parameter one of the following:

• IMPLIED_VERSION
• MAX
• A decimal value of 1 or 2

,RETCODE=retcode

Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.

,RSNCODE=rsncode

Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.

IBM recommends that you use the modify and execute forms in the following order:

• Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
• Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
• Use MF=(E,list_addr,NOCHECK), to execute the macro.

,list addr

The name of a storage area to contain the parameters.

,attr

An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.

,COMPLETE

Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

,NOCHECK

Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

None.

When IXGCONN macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.

The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.