The parameters are explained as follows:

,#SERVERS=#servers

,#SERVERS=1

When SCOPE=SOME, SERVER=server and REQTYPE=STOP are specified, use this optional input parameter to contain the number of server instances on the local system that are to be stopped. If #SERVERS exceeds the number of instances, all instances of the indicated server on the local system are to be stopped. The default is 1.

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

,DESCRIPTION=description

When REQTYPE=START is specified, use this required input parameter to contain a description of the server. 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. The description will appear in various XCF messages and diagnostic data reports. The description is intended to help installations and service personnel understand the function, purpose, or role of the server.

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

,FDI=fdi

,FDI=120

When REQTYPE=START is specified, use this optional input parameterto indicate the server failure detection interval, which is the number of seconds that the server can appear to be unresponsive before the system considers it to have failed. If the server is deemed to have failed, the server task is subject to being terminated by XCF (abend 00C reason x164).

A server is deemed responsive if it returns to the XCF server exit stub routine, and unresponsive otherwise. If the server is processing a request for which there is an associated timeout value, the XCF monitor expects the server exit to return to XCF within FDI seconds after the timeout expires. If there is no associated timeout, the server exit is expected to return to XCF within FDI seconds.

For example, suppose the server exit was called to process a client request that had a timeout value of 100 seconds (IXCSEND MSG=REQUEST RESPTIME=100). XCF would allow the server to process the request for as long as 100 seconds. After 100 seconds have elapsed, XCF allows up to FDI more seconds for the server exit routine to return to XCF. If it fails to do so, XCF deems the server to be unresponsive.

If not specified, the server failure detection interval is set to two minutes (120). The FDI value must be between 1 and 3600, inclusive.

The default is 120.

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

,FEATURES=features

,FEATURES=0

When REQTYPE=START is specified, use this optional input parameter to contain a "feature string". The feature string indicates the features supported by the server and is mapped by ixcysrvr_tFeatures in macro IXCYSRVR. The interpretion of the feature level and feature flags within the feature string is determined by the server.

When using IXCSEND SENDTO=SERVER to send a request to a server, clients can specify the features that a server must support in order to process a request. As explained in the IXCYSRVR macro, XCF compares the features requested by the client to the features supported by the server to determine whether the server is capable of processing a client request. If no server supports the required features, the request is cancelled and acknowledged with a response code indicating "no receiver". The default is 0.

To code: Specify the RS-type name, or address in register (2)-(12), of an 8-character field that contains the feature string.

,INFO=info

,INFO=0

When REQTYPE=START is specified, use this optional input parameter to contain information about the server. The content and interpretation of this information is determined by the server. XCF saves a copy of the indicated data. The saved copy is passed to the server exit routine whenever it is called. A copy of the data is also visible to other processes in the sysplex through queries that return information about the server. Thus related componentry, such as a sender, can obtain whatever information the server cares to define and share about itself. The default is 0.

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

,MAXCLIENT=maxclient

,MAXCLIENT=MINCLIENT

When REQTYPE=START is specified, use this optional input parameter to contain a number that identifies the largest client level that the server will accept. MAXCLIENT must be greater than or equal to MINCLIENT. The default is MINCLIENT.

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

,MAXLEVEL=maxlevel

,MAXLEVEL=MINLEVEL

When REQTYPE=START is specified, use this optional input parameter to contain a number that identifies the maximum server level supported by this server. MAXLEVEL must be greater than or equal to MINLEVEL.

The default is MINLEVEL.

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

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

Use this optional input parameter to specify the macro form.

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 might be coded with 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.

,list addr

The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1)-(12).

,attr

An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.

,COMPLETE

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

,MINCLIENT=minclient

,MINCLIENT=0

When REQTYPE=START is specified, use this optional input parameter to contain a number that identifies the smallest client level that is acceptable to the server. In combination with MAXCLIENT, MINCLIENT defines the range of client levels whose requests the server will accept. The interpretation of level is determined by the client.

When a client sends a request, it specifies its level. When the request arrives on the server system, XCF compares the client level to the range of client levels acceptable to the server. If the client level does not fall within the acceptable range, the server is not eligible to process the request.

The default is 0.

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

,MINLEVEL=minlevel

,MINLEVEL=0

When REQTYPE=START is specified, use this optional input parameter to contain a number that identifies the smallest server level supported by this server. In combination with MAXLEVEL, MINLEVEL defines the range of levels supported by the server. The interpretation of level is determined by the server.

When a client sends a request, it specifies the range of server levels that are acceptable for processing the request. When the request arrives on the server system identified by server name, XCF compares the range of server levels requested by the client to the range of levels supported by the server. If the requested range does not intersect the supported range, the server is not eligible to process the request.

The default is 0.

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

,MODE=NORMAL

,MODE=IMMEDIATE

When REQTYPE=STOP is specified, use this required parameter to indicate whether the servers being stopped are to finish pending work

,MODE=NORMAL

The server is to be stopped as soon as it finishes processing both its current request as well as any pending work that might have been queued prior to the stop request being recognized.

Requests that arrive after the stop request is recognized will be cancelled if there is no other suitable server instance to process the request.

,MODE=IMMEDIATE

The server is to be stopped as soon as it finishes processing its current request (if any). The server will not process any pending work that might have been queued. If stopping the server instance leaves the pending work with no suitable server to process it, the pending work is cancelled. For example, pending client requests would be discarded and acknowledged with a "no receiver" response code.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

Use this optional input parameter to specify the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. 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.
• 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 are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

• 0, if you use the currently available parameters.

To code: Specify one of the following:

• IMPLIED_VERSION
• MAX
• A decimal value of 0

,REQTYPE=START

,REQTYPE=STOP

Use this required parameter to indicate whether a server is to be started or stopped.

REQTYPE=START

Start an instance of the named server.

If the request is valid, the XCF service routine will not return to the caller until the server is stopped. The XCF service routine will repeatedly call the indicated server exit routine (SERVEREXIT) to processs client messages (requests). If there are no messages to process, the work unit is suspended until one arrives.

REQTYPE=STOP

Stop one or more servers on the local system.

XCF will initiate stop processing for the indicated instances of the server on the local system, and then return to the caller. The actual stopping of the servers completes asynchronously to the stop request. Thus on return from the IXCSRVR invocation, the indicated server instances might or might not have been stopped.

,RESPBIND=INSTANCE

,RESPBIND=ADDRSPACE

,RESPBIND=SYSTEM

When REQTYPE=START is specified, use this optional parameter to indicate the default recovery bind XCF should establish for the server with respect to response processing. This specification determines the circumstances for which XCF will cancel responses that this server instance is expected to send. Canceling a response implies that its recipient does not need to wait for its timeout value to expire to discover that no response was sent.

The server exit routine can update the SXPL_RespBind field to change the default response bind on a request by request basis. The default is RESPBIND=INSTANCE.

,RESPBIND=INSTANCE

XCF is to associate responsibility for sending responses to this instance of the server. If the server is stopped, XCF is to cancel any outstanding responses that the server was expected to provide.

This option is intended for servers whose server exit is responsible for sending responses. In such cases, termination of the server instance implies no further responses will be sent. Termination of the server instance includes task termination, address space termination, system termination, or simply stopping the server.

This option can be used even if there are other work units responsible for sending the responses. However, there will in effect be a race condition between such responses and the XCF cancel processing. The responses might or might not be presented to the intended recipient. The IXCSEND service might or might not accept the response for delivery.

,RESPBIND=ADDRSPACE

XCF is to associate responsibility for sending responses to the server address space. When the address space terminates, XCF cancels any outstanding responses that the server instance was expected to provide.

This option is intended for servers whose server exit routine does not send responses. Instead, the server exit routine arranges for other work units in the server address space to send responses. Since the server exit is not responsible for sending responses, XCF should not cancel the expected responses if the server instance terminates. Not until the server address space terminates should XCF cancel the responses.

This option can be used even if there are work units in other address spaces responsible for sending the responses. However, there will in effect be a race condition between such responses and the XCF cancel processing. The responses might or might not be presented to the intended recipient. The IXCSEND service might or might not accept the response for delivery.

,RESPBIND=SYSTEM

XCF is to associate responsibility for sending responses to the local system. When the system terminates, XCF cancels any outstanding responses that the server instance was expected to provide.

This option is intended for servers whose server exit routine does not send responses. Instead, the server exit routine arranges for work units in an address space other than the server address space to send responses. Since neither the server exit nor the server address space is responsible for sending responses, XCF should not cancel the expected responses when the server instance or the server address space terminates. Not until the system terminates should XCF cancel the responses.

If the server arranges for some other system in the sysplex to send responses, there will be a race condition between such responses and the XCF cancel processing. The responses sent by the third party systems might or might not be presented to the intended recipient.

,RETCODE=retcode

Use this optional output parameter into which the return code is to be copied from GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.

To code: Specify the RS-type name of a fullword field, or register (2)-(12) or (15), (GPR15), (REG15), or (R15).

,RSNCODE=rsncode

Use this optional output parameter into which the reason code is to be copied from GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.

To code: Specify the RS-type name of a fullword field, or register (0) or (2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).

,SCOPE=SOME

,SCOPE=ALL

When SERVER=server and REQTYPE=STOP are specified, use this required parameter to indicate how many instances of the indicated server are to be stopped.

,SCOPE=SOME

The indicated number of server instances on the local system are to be stopped.

,SCOPE=ALL

All instances of the indicated server on the local system are to be stopped.

,SERVER=server

When REQTYPE=START or REQTYPE=STOP is specified, use this required input parameter to contain the name of the server.

Server names are mapped by ixcysrvr_tName (macro IXCYSRVR). Server names consist of four 8 byte sections. Each 8 byte section must be left justified, padded on the right with EBCDIC blanks as needed. Each section can contain any alphanumeric (A-Z,a-z,0-9), national (@,#,$), or underscore character. Any section but the first can be entirely blank. Server names are case sensitive. The name will appear in various XCF messages and diagnostic data reports. Clients using the IXCSEND service to send requests to a server can identify the target server by its name.

To avoid names used by IBM, do not begin server names (section 1) with the letters A through I or the character string SYS.

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

,SERVEREXIT=serverexit

When REQTYPE=START is specified, use this required input parameter to specify the routine that XCF is to call to process the indicated request type. The exit receives control under the current thread in the same addressing mode and ASC mode as the caller. On entry, R1 contains the address of the server exit parameter list (SXPL) that is mapped by ixcysrvr_tSXPL in IXCYSRVR. The exit is responsible for establishing its own recovery environment.

To code: Specify the RS-type name, or address in register (2)-(12), of a field that contains the routine.

,SERVERID=serverid

When REQTYPE=STOP is specified, use this required input parameter to specify the name of the server id of the server instance that is to be stopped. If a specified server ID does not identify an active server instance on the local system, the request is rejected.

The storage containing the indicated SERVERID can reside in the primary address space of the caller, or in a space addressable through a public entry on the dispatchable unit access list (DU-AL) or in a common area data space.

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

,USERDATA=userdata

,USERDATA=0

When REQTYPE=START is specified, use this optional input parameter to contain user data that is to be associated with the server. A copy of the user data is presented to the server exit routine. The default is 0.

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