IOAGATE

• Overview

• IOAGATE EXEC Parameters

• IOAGATE Modify Commands

• Diagnostic SNAP Modify Commands

Overview

This chapter contains a brief overview of the IOAGATE and its components, followed by the parameters and commands that an administrator needs to operate IOAGATE.

IOAGATE is a mainframe software communications gateway (middleware) that enables INCONTROL mainframe applications to communicate with other mainframe and non-mainframe applications over the network.

Client applications access INCONTROL products by means of an application server through IOAGATE.

The following figure shows IOAGATE components:

Figure 98 IOAGATE Components

IOAGATE supports multiple concurrent application servers of different applications and their clients. A single IOAGATE can support Control‑M, Control‑D/Page On Demand, Control‑D File Transfer option, and Control‑O applications.

IOAGATE EXEC Parameters

This section describes the startup EXEC parameters in the IOAGATE STC job or in the start command that are used to alter IOAGATE behavior.

TRACE

Purpose

Handling of IOAGATE traces.

Syntax

Table 257 Syntax for Parameter TRACE

Syntax	Description
TRACE=<trace list>	Samples of trace list formats:
TRACE=20	Turn ON trace level 20
TRACE=(21,200)	Turn ON trace levels 21 AND 200
TRACE=-200	Turn OFF trace levels 200
TRACE=(-21,-40)	Turn OFF trace levels 21 AND 40
TRACE=(1:512)	Turn ON all trace levels
TRACE=(-1:-512)	Turn OFF all trace levels
TRACE=SHOW	Show current trace levels

For example, to set TRACE parameter to ‘SHOW’ and PSFX parameter to ‘W’, do one of the following:

• In an STC Job, enter the following commands:

  Copy

      //IOAGATE JOB MSGLEVEL=1               
      //         JCLLIB  ORDER=IOAP.V610.PROCLIB  
      //         INCLUDE MEMBER=IOASET            
      //IOAGATE  EXEC  IOAGATE,                   
      //         REG=0M,                          
      //         TRACE=SHOW,                      
      //         PSFX=W                         

• In a start command, enter the following:

  Copy

  /S IOAGATE,TRACE=SHOW,PSFX=W

PSFX

Purpose

Defines the parameter member (ECAPARM) suffix.

If this parameter is omitted, member ECAPARM is loaded.

For example, PSFX=D causes IOAGATE to load the ECAPARMD member.

Syntax

where # is any valid character for the member name suffix.

Overriding Channel Definitions

The user can override link definitions of a selected channel using the EXEC parameters described in the following topics.

CHAN

Purpose

Identify the channel that is to be affected by the PORT or APPLID parameters.

If this parameter is omitted, the first channel in member ECAPARMx is affected.

User must provide the PORT or APPLID parameters to match the channel protocol (TCP/SNA).

Syntax

where xx is the Channel ID (defined in member ECAPARMx under the CHANNEL entry).

Description

If CHAN is not defined in member ECAPARMx, the PORT/APPLID is ignored.

PORT

Purpose

Alter the TCP/IP port defined for a channel. The channel ID is specified by the CHAN parameter.

Syntax

where nnnnn is a number between 1024 and 65534.

APPLID

Purpose

Alter the SNA LUs defined for a channel. The channel ID is specified by the CHAN parameter.

Syntax

Table 258 Syntax for APPLID Parameter

Statement	Description
APPLID=<luname>	Single LU name for multi-connection channel.
APPLIDS=(luname1,luname2)	Two LUs (Send and Receive) for Dual-connection channel.

where luname, luname1 and luname2 are valid SNA lu names.

IOAGATE Modify Commands

The following modify commands are available to the IOAGATE operator. These commands enable the operator to diagnose the IOAGATE and applications server address space status. The operator can then execute commands such as starting and stopping components.

IDL

Purpose

The IDL modify command passes on the command specified as a parameter, to the IDL facility for processing. For more information, refer to Modify commands.

Syntax

SVCDUMP

Purpose

Initiates an SVC dump.

Syntax

TRACE

Synonyms

DEBUG

Purpose

Handling IOAGATE traces. Trace data is written to the DATRACE DD statement.

Syntax

To start or stop trace levels

To show trace level status

Table 259 Samples of Trace List Formats

Statement	Description
TRACE=20	Turn ON trace level 20
TRACE=(21,200)	Turn ON trace levels 21 AND 200
TRACE=-200	Turn OFF trace levels 200
TRACE=(-21,-40)	Turn OFF trace levels 21 AND 40
TRACE=(1:512)	Turn ON all trace levels
TRACE=(-1:-512)	Turn OFF all trace levels

Table 260 Subset of IOAGATE Trace Levels

Trace Level	Trace Output
20	Communications general trace
21	Send or Receive buffers If data compression is enabled in the application server, the send buffer of that server is printed in compressed format. Use level 23 to display uncompressed data.
22	Send or Receive message header summary
23	Send or Receive uncompressed buffers Disables data compression for all application servers while ON.
40	SNA communication trace
150	Application server management trace. This modify TRACE command must be issued for the application server address space and not on the IOAGATE address space.
200	TCP/IP communication modules trace

STATUS

Synonyms

SHOWASID

STATASID

ASID

Purpose

Display application server task status.

Syntax

To list all application servers tasks

To list tasks of a specific application server address space

where ASID is the application server ID. The application server ID is the sequence number of the address space at IOAGATE startup.

Sample Output

This command lists the server tasks of IOAGATE and produces the following output (JESMSGLG):

Table 261 Description of Output Fields

Output Field	Description
SERVER	Server type.
TASK	Task identification specified in the format snnn.mm. s - Short application code nnn - Unique Server ID mm - Address space ID
STATUS	Server current working status. Possible statuses are: READY - Server ready to receive requests. BUSY - Server is busy handling a transaction. START - Server is in starting process. UP - Server is up (server without mailbox). FAILED - Server failed. DOWN - Server is down. SUSPEND - Server recovery was suspended. WAIT - Server is waiting for main task (CM) readiness. PENDING - Server is not responsive.
CHANNEL/SIID	For a non-busy task, this field displays the channel name in the format TTNN, where TT is the channel type (DC/MC) and NN is the channel ID. For busy tasks, this field displays the current serviced instance ID
PROCEDURE. STC/MODULE	For a CM task, this field displays the procedure name of the application server in the format XXXXXFMM. XXXXX - Procedure prefix name. F - ECAPARM suffix name. MM - Address space ID. For other tasks, this field displays the server program name
UTILIZATION	The server service handling utilization

For details, see messages ECAG34I and ECAG35I in the INCONTROL for z/OS Messages Manual.

SHOWCHAN

Synonyms

CHAN

Purpose

Display channels status.

Syntax

To list all channels

To list only enabled channels

Table 262 Description of Output Fields

Header	Description
CHAN	Channel in the format TTNN, where TT is the channel type (DC/MC) and NN is the channel ID.
PROT	Channel protocol. Valid values are SNA and TCP, for SNA protocols and TCP/IP protocols, respectively.
TASK	Channel Task identity. Valid values are SNDR (Sender) or RCVR (Receiver) for DC Channel, and LSNR for MC channel.
VENDOR	TCP/IP vendor. Valid values are IBM and CA.
SUBS	Sub-system name. Valid only for vendor CA and protocol TCP/IP.
PORT/LU	Port /LU defined to the channel.
STATUS	Current status of the channel. Possible values are: DISABLED – Channel is disabled for use. LISTENING – Channel is listening for connections. Displayed for DC channel. CONNECTED – Channel is connected. Displayed for DC channel. UP/OPEN – Channel communication is open for incoming connections. Displayed for MC channel. UP/CLOSED – Channel communication is UP but unavailable (CLOSED) for incoming connections. Displayed for MC channel. DOWN – Channel communication is down.
LINKS	Current number of connections to the channel (TCP/IP only).
LINKS%	Percentage of connections utilized out of all supported connections.
APPL	Applications (in short name format) supported by this channel.

SHOWTOKEN

Purpose

Displays IOAGATE MVS token

Syntax

To show IOAGATE MVS tokens, enter the following:

The contents of the current IOAGATE token are displayed in a ECAG3HI message.

STARTASID

Synonyms

SASID

Purpose

Start application server address space.

The command can be issued after the application server was shut down due to operator command STOPASID or address space failure.

Syntax

where ASID is the application server address space ID.

Description

The ID is the sequence number of the address space that has been assigned by IOAGATE at startup. This number is the suffix of the application server procedure step. You can find it by using the STATUS command, and in message ECAB50I (in DD DAIGLOG). For example, the ASID 01 startup message:

STOPASID

Synonyms

PASID

Purpose

Stop an application server address space.

Syntax

where ASID is the application server address space ID.

Description

The ID is the sequence number of the address space that has been assigned by IOAGATE at startup. This number is the suffix of the application server procedure step. You can find it by using the STATUS command, and in message ECAB50I (in DD DAIGLOG). For example, the ASID 01 startup message:

STARTTID

Synonyms

STID

Purpose

Start server task under an application server address space.

Syntax

Table 263 Syntax for Command STARTID

Field	Description
Task ID	Unique ID of the server task in the format snnn. s - Short application code. nnn - Server number.

Description

You can find the server task ID by using the STATUS command, and in the messages ECAB27I, ECAB49I, ECAG4DE and ECAG41E.

STOPTID

Synonyms

PTID

Purpose

Stop server task under an application server address space.

Syntax

Description

Table 264 Syntax for Command STOPTID

Field	Description
Task ID	Unique ID of the server task in the format snnn. s - Short application code. nnn - Server number.

You can find the server task ID by using the STATUS command, and in the messages ECAB27I, ECAB49I, ECAG4DE and ECAG41E.

MODASID

Synonyms

FASID

Purpose

Send a modify command to an application server that can receive and perform such a command.

Syntax

To send a command to all application servers that can receive modify commands:

To send a command to a specific address space that can receive modify commands

Table 265 Syntax for Command MODASID

Field	Description
ASID	Application server address space ID. Optional. If not specified, the command is applied on all application servers.
command	Application server supported command. The following commands are available: MODAPPL: Passes the MODIFY command to the IOAAS application server. LOADTREE: Loads the Recipient and Approval Tree. See Loading the Recipient and Approval Tree. DISPLAY: Displays a list of active users in the Application Server. See Displaying a List of All Active Users (for Control-D) or Displaying a List of All Active Users (for Control-O). LOGOUT: Forces logout from a user session in IOAAS. See Forced user session logout. SHARPTRC: Adjusts performance trace levels for IOAAS. See Adjusting the scope of the performance trace in IOAAS.

Sample Output

This command produces the following output (DAIGLOG):

STOP

Purpose

Stop IOAGATE and all its application servers.

Syntax

Output

SHOWMAP

Synonyms

MAP

Purpose

List the map used by the Control‑O Gateway to Gateway connections.

Syntax

Sample Output (JESMSGLG)

Table 266 Description of Output Fields

Header	Description
CHAN	Channel in format MCID, where MC is the type and ID is the channel ID
TASK	ID of the communication task that handles the connection
PARTNER	NODE of the partner IOAGATE
PORT	Port of the partner IOAGATE
CONNECTOR	LOCAL or PARTNER
STATUS	Statuses are: READY TO CONNECT - Temporary initial status RECONNECTED - Connection established after it has been lost DISCONNECTED - Passive side lost connection DISABLED - Invalid MAP entry disabled CONNECTION IN PROGRESS - Connect in progress RETRYING - Connect failed and will be retried CONNECTED - Connection established WAITING FOR CONNECTION - Passive side awaiting connection
SOCKET	Socket number used for the connection
HOST	Hostname or IP address where partner IOAGATE runs as defined in MAP

For more details see messages ECAP20I, ECAP21I and ECAP22I in the INCONTROL for z/OS Messages Manual.

ALLOCS

Purpose

List all address space allocated files.

Syntax

Sample Output

Output (JESMSGLG):

Table 267 Description of Output Fields

Header	Description
DYN	Dynamic allocated file.
JCL	Static allocated file.

STORSUM

Purpose

Print virtual storage summary.

Syntax

Sample Output

Figure  99 Sample Output DAPRENV

SHOWSIBS

Synonyms

SIBS

Purpose

Print the total number of Service Instance Control Blocks in IOAGATE queues.

These blocks represent the messages held in IOAGATE.

Syntax

Sample Output (in JESMSGLG)

STATON

Purpose

Start the IOAGATE communication statistics collection.

Syntax

where nnn is the time interval (a number from 001 through 999).

Description

If the time interval is omitted, the interval is set to 10 minutes. The time interval is the time between each storing of the collected communications statistics data. Only data for the last six time intervals are saved.

Output (DAIGLOG)

STATOFF

Purpose

Stop IOAGATE communication statistics collection.

Syntax

Output (DAIGLOG)

STATRESET

Purpose

Reset communication statistics.

Syntax

Output (DAIGLOG)

STATALL

Purpose

Print detailed statistics data.

(Table line levels are: Time interval, Channel, Application, and Message type level).

Syntax

Output (DATRACE)

Figure 100 Sample Output (DATRACE)

Table 268 Output Format Table

Header	Description	Remarks
Chan ID	Channel ID.	List the Enabled channels only.
Appl Name	Application short name.	List the applications supported by the channel.
TRAN ID	Transaction ID.	The main transaction IDs are listed in the table below.
Data Type	Statistics data type included in the table line.	See Data Types
Total hh:mm- (1) hh:mm (2)	Total accumulating statistics from statistics collection start time (1) until now (2).
n hh:mm- (1) hh:mm (2)	Statistics collected in time interval n, from interval start (1) until interval end (2).	Currently up to 6 time intervals are available for display. You can modify the time interval by using parameter INTERVAL in the STATON command.

Table 269 Main Transaction ID List

Application	IDs
Control‑D/Page On Demand and Control‑D File Transfer option	IDs: M - Management messages R - User request
Control‑M	IDs: 1 - Send User Dailies request A - Calendar list request B - Global Prefixes request D - Download F - Definitions download G - Table list request I - Information request J - Remote Forcejob request L - Folder Library List request O - Order or force request P - Upload R - User request S - Synchronization T - Definitions upload U - Database update V - Workload update W - Workload sync
Control‑O	IDs: B - Rules (receive) G - Rules (send)

Data Types

Table 270 Data Types

Data Type	Description
COUNTERS:	Numeric Counters section. Counters are displayed in the format nn,nnn$ where $ is ‘K’ for Kilo (x 1,024), ‘M’ for Mega (x 1,024K) TRANS - Number of transactions MSGS -IN - Number of incoming messages MSGS –OUT - Number of outgoing messages BYTES-IN - Number of incoming bytes BYTES-OUT - Number of outgoing bytes
AVRG TIME:	Average transaction response time section. Timers are displayed in the format xx.xxx$ where $ is ‘s’ for seconds, ‘m’ for minute, ‘h’ for hours and ‘d’ for days. INP-Q.TIME - Input queue duration OUT-Q.TIME - Output queue duration SRVER-RESP - Application server response time PRTNR-RESP - Partner response time OTHER.TIME - Other transaction states duration TOTAL-RESP - Total transaction response time

STATSUM

Purpose

Print summary statistics data

(Table line levels are: Channel, Application, Counter type).

Syntax

Output (DATRACE)

Figure 101 Sample Output DATRACE

Table  271 Output Format Table

Header	Description	Remarks
Chan ID	Channel ID.	List the ‘Enabled’ channels only.
Appl Name	Application short name	List the applications supported by the channel.
Data Type	Statistics data type included in the table line.	See Data Types
Total hh:mm- (1) hh:mm (2)	Total accumulating statistics from statistics collection start time (1) until now (2).
n hh:mm- (1) hh:mm (2)	Statistics collected in time interval n, from interval start (1) until interval end (2).	Currently up to 6 time intervals are available for display.
	You can modify the time interval by using the INTERVAL parameter in the STATON command.

CLOSE

Synonyms

CLOSE

Syntax

To stop handling incoming connections for the specific channel:

To stop handling incoming connections for all channels:

To stop handling incoming connections and shutdown IOAGATE when all clients have been disconnected:

OPEN

Synonyms

OPEN

Purpose

Resume handling incoming connections.

Syntax

To resume handling incoming connections by the specific channel that was previously closed:

To resume handling incoming connections all channels that were previously closed:

LOGINMSG

Purpose

Controls the destinations where ECAG62I messages will be sent. These messages indicate that a user successfully logged on to IOAGATE over a multiple connection (MC) TCP channel.

Synonyms

Syntax

To show the current values of the LOGINMSG parameter in all MC channels, enter the following modify command:

This command produces the following output (JESMSGLG):

To dynamically override the value of the LOGINMSG parameter in all MC channels to one of the values listed below, enter the following modify command:

In the preceding syntax statement, value can have the following meanings:

YES – The ECAG62I message is issued to LOG (DAIGLOG) and WTO

NO – The ECAG62I message is issued to LOG (DAIGLOG) only

OFF – The ECAG621 message is not issued

WTO – The ECAG62I message is issued to WTO only

LOG – The ECAG62I message is issued to LOG (DAIGLOG) only

LOG+WTO – The ECAG62I message is issued to both LOG (DAIGLOG) and WTO

WTO+LOG – The ECAG62I message is issued to both LOG (DAIGLOG) and WTO

To dynamically override the value of the LONGINMSG parameter in a specific MC channel, enter the following modify command:

In the preceding syntax statement, value can have the meanings shown above, and channel-id is the specific MC channel whose value you want to change.

REFRESH

Purpose

REFRESH (reload) ECAIPLSx, which is the list of valid IP addresses from which IOAGATE can accept connection establishment requests (IP list).

Syntax

Where x is the suffix (optional) of ECAIPLS member.

Diagnostic SNAP Modify Commands

The following commands are for diagnostic usage. Use only when asked by a BMC representative.

Area SNAPs are written to the DATRACE DD statement.

PRINTSST

Synonyms

PSST

Purpose

Print Servers Status Table area.

This table represents all the applications address space tasks communicating with IOAGATE.

Syntax

To print all SST entries

To print SST entry of a specific task

PRINTSDT

Synonyms

PSDT

Purpose

Print Server Descriptor Table area.

This table represent all the servers tasks initialization definitions (built based on member ECAPARM)

Syntax

To print all SDT entries

To print SDT entry of a specific server task

PRINTSTD

Synonyms

PSTD

Purpose

Print Subtask Descriptor Table area. This table represent all the IOAGATE tasks.

Syntax

To print all STD entries

To print STD entry number nn

PRINTCMT

Synonyms

PCMT

Purpose

Print Communication Table area. This table represents the TCP/IP communication tasks.

Syntax

To print all CMT entries

To print CMT entry number nn

PRINTALL

Synonyms

PALL

Purpose

Print all tables areas.

Syntax

PRINTWCT

Synonyms

PWCT

Purpose

Print gateWay master Control Table. This table includes internal IOAGATE data.

Syntax

PRINTSIB

Synonyms

PSIB

Purpose

Print Service Instance control Blocks area. These blocks represent the messages held in IOAGATE.

Syntax

To print all SIB entries: