IOSVRYSW — Vary switch service

Description

IOSVRYSW provides an interface to the VARY SWITCH process to configure a switch port online or offline to Dynamic Channel Path Management (DCM). Invoking this interface for a switch port also causes the specific managed device paths to be varied online or offline. An online request causes the managed channel paths to become eligible to DCM. An offline request causes the managed channel paths to be removed from the control units connected to the managed channel path IDs (CHPIDs) at the specified ports. This command affects only managed device paths. Non-managed paths must be varied online or offline separately.
Note: VARY SWITCH command performs the same function when it is issued from a console. For more information, see Placing a Switch Port Online or Offline in z/OS MVS System Commands.
Macro IOSDVSAP maps each element of the array of resource elements that is passed to the VARY SWITCH programming interface. Each element is created by a separate IOSVRYSW BUILD invocation and represents a vary switch port online, offline, or offline and unconditional request.
Note: The caller is responsible for obtaining the right amount of storage for the array of resource elements before the first IOSVRYSW BUILD request.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Supervisor state, or PSW key 0-7, or APF-authorized
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 31-bit
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts.
Locks: No locks held
Control parameters: Must be in the primary address space

Programming requirements

Programs invoking this interface must include mapping macro IOSDVSAP.

Restrictions

None.

Input register information

Before issuing the IOSVRYSW 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.
Register
Contents
0
Undefined
1
Used by the service
2-13
Undefined
14-15
Used by the service

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0
Reason code (valid for TYPE=INVOKE, unpredictable otherwise)
1
Unpredictable
2-13
Unchanged
14
Unpredictable
15
Return code (valid for TYPE=INVOKE, unpredictable otherwise)
When control returns to the caller, the ARs contain:
Register
Contents
0-15
Unchanged

Performance implications

None.

Syntax

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

Syntax Description
   
   name name: symbol. Begin name in column 1.
   
␢ One or more blanks must precede IOSVRYSW.
   
IOSVRYSW  
   
␢ One or more blanks must follow IOSVRYSW.
   
TYPE=BUILD  
   
       ,REQUEST=ONLINE Default: ONLINE
   
       ,REQUEST=OFFLINE  
   
             ,OPTION=UNCOND Default: NONE
   
       ,SWITCHDEV=switchdev switchdev: RS-type name, or address in register (2)-(12).
   
       ,PORTADDR=portaddr portaddr: RS-type name, or address in register (2)-(12).
   
      INVOKE  
   
       ,DATAADDR=dataaddr dataaddr: RS-type name, or address in register (2)-(12).
   
       ,DATANUM=datanum datanum: RS-type name, or address in register (2)-(12).
   
   ,RETCODE=retcode retcode: RS-type address or register (2) - (12). Can only be specified with an INVOKE request.
   
   ,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12). Can only be specified with an INVOKE request.
   
   ,MF=(E,list addr) list addr: RS-type address or register (2) - (12).
   ,MF=(E,list addr,COMPLETE) Default: COMPLETE
   

Parameters

The parameters are explained as follows:

TYPE=BUILD
Specifies a required keyword input which indicates that the macro is being invoked to construct vary switch parameters.
REQUEST=ONLINE
REQUEST=OFFLINE
Specifies an optional keyword input which indicates the type of request to process.
  • ONLINE: The request is to configure a switch port online to Dynamic Channel Path Management. The default is ONLINE.
  • OFFLINE: The request is to configure a switch port offline to Dynamic Channel Path Management.
OPTION=UNCOND
Specifies an optional keyword input which indicates an additional option to be processed along with an OFFLINE request.

UNCOND: This option is used to specify an UNCOND request on the VARY PATH commands invoked as a result of the VARY SWITCH request. Adding the UNCOND keyword to a VARY PATH,OFFLINE command results in the system taking offline the last path to devices that are online but unallocated.

SWITCHDEV=switchdev
Specifies an RS-type name, or address in register (2)-(12), of a required halfword input which indicates the switch device number to be affected.
PORTADDR=portaddr
Specifies an RS-type name, or address in register (2)-(12), of a required byte input which indicates the port address to be affected.
TYPE=INVOKE
Specifies a required keyword input which indicates to perform the requested Vary Switch function built by one or multiple IOSVRYSW BUILD requests.
DATAADDR=dataaddr
Specifies an RS-type name, or address in register (2)-(12), of a required 4 byte input that contains the address to the array of resource elements to be processed. Each element is created by an IOSVRYSW BUILD invocation and is mapped by mapping macro IOSDVSAP.
DATANUM=datanum
Specifies an RS-type name, or address in register (2)-(12), of a required fullword input that contains the number of elements in the array of resource elements to be processed.
RETCODE=retcode
Specifies an RS-type name of an optional fullword output variable, or register (2)-(12), into which the return code is to be copied from GPR 15.
Note: This keyword can only be specified with an INVOKE request.
RSNCODE=rsncode
Specifies an RS-type name of an optional fullword output variable, or register (2)-(12), into which the reason code is to be copied from GPR 0.
Note: This keyword can only be specified with an INVOKE request.
MF=(E,list addr)
MF=(E,list  addr,COMPLETE)
Specifies the execute form of the IOSVRYSW macro.
list addr
Specifies the area that the system uses to contain the parameters.
COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters. COMPLETE is the default.

ABEND codes

None.

Return and reason codes

Note: There are no return or reason codes for TYPE=BUILD.

When the system returns control to the caller, GPR 15 (and retcode, when you code RETCODE) contains a return code.

The following table identifies the hexadecimal return codes:

Table 1. Return Codes for the IOSVRYSW Macro
Hexadecimal Return Code Meaning and Action
00

Meaning: Successful completion.

Action: None required.
10

Meaning: An unexpected error occurred in vary switch processing.

Action: Verify the configuration in effect and resubmit the request. If the request fails again for the same reason, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM® Support Center.
FF04

Meaning: Storage passed on the DATAADDR was not accessible by the service.

Action: Verify that accessible storage is being passed.
FF08

Meaning: The attempt to queue a work element to the IOS address space failed. Request is currently not able to be performed.

Action: Search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.
FF0C

Meaning: VSAP data is readable but not valid.

Action: Verify that the correct data is being passed.
FF10

Meaning: Caller is not in a valid environment to invoke the IOSVRYSW API.

Action: Insure that the caller is running in the correct environment.
FF14

Meaning: Module IOSVVSWF suffered a catastrophic error. Function could not be processed.

Action: Search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.
FF18

Meaning: Module IOSVVSWF could not establish a recovery environment.

Action: Resubmit the request. If the request fails again for the same reason, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.

Hexadecimale Reason Codes: None.

IOSVRYSW—List form

Use the list form of the IOSVRYSW macro together with the execute form of the macro for applications that require reentrant code. The list form of the macro defines an area of storage, which the execute form of the macro uses to contain the parameters.

Syntax

The list form of the IOSVRYSW macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede IOSVRYSW.
   
IOSVRYSW  
   
␢ One or more blanks must follow IOSVRYSW.
   
MF=(L,list addr) list addr: Symbol.
MF=(L,list addr,attr) attr: 1- to 60-character input string
MF=(L,list addr,0D) Default: 0D
   

Parameters

The parameters are explained as follows:

MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the IOSVRYSW macro.

list addr is the name of a storage area to contain the parameters.

attr is 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.

Examples

An example of issuing three IOSVRYSW TYPE=BUILD and an IOSVRYSW TYPE=INVOKE invocations to process three switch ports.

Initial Setup:
  • Define the list form of the macro
  • Obtain storage for the array of resource elements (See mapping macro IOSDVSAP in z/OS MVS Data Areas in the z/OS Internet library)
  • Establish addressability to the area
  • Clear the area
  • Set up a pointer, pointing to the beginning of the area
  • Base VSAP_RESOURCE structure on the pointer that points to the beginning of this area.
  • For EACH port to be altered (for each request), issue IOSVRYSW TYPE=BUILD:

    • IOSVRYSW TYPE=BUILD,
                  REQUEST=ONLINE,
                  SWITCHDEV=switch
                  PORTADDR=port_address

    • Advance the pointer by length of VSAP_RESOURCE to the next slot in the array

    • IOSVRYSW TYPE=BUILD,
                  REQUEST=ONLINE,
                  SWITCHDEV=switch
                  PORTADDR=port_address

    • Advance the pointer by length of VSAP_RESOURCE to the next slot in the array

    • IOSVRYSW TYPE=BUILD,
                  REQUEST=ONLINE,
                  SWITCHDEV=switch
                  PORTADDR=port_address

    • Issue IOSVRYSW TYPE=INVOKE to process the requests, passing in the pointer to the array of resource elements and the number of elements to the processing module.

    • IOSVRYSW TYPE=INVOKE,
                  DATAADDR=pointer to the array of resource elements,
                  DATANUM=number of elements to be processed
                          (ports to be altered),
                  RETCODE=RETURN_CODE,
                  RSNCODE=REASON_CODE,
                  MF=(E, IOSVRYSW_LIST)