CHAPTER 10

Using Cisco IOS for S/390 API and Socket Applications

This chapter describes some API and socket application programs that you might find useful. It includes these sections: • What Example Applications are Provided? Briefly describes how these examples are presented and their uses. • ACSHELLO This TSO command acts as a server that can be queried by clients to obtain information about the host on which the ACSHELLO program is executing. • FINGER This TSO command obtains information about users of a system. • TTCP This TSO command acts as a data source or sink facility. • WHOIS This TSO command queries a default or user-specified WHOIS server to obtain information about a user-specified name.

What Example Applications are Provided? The FINGER, WHOIS, ACSHELLO, and TTCP application programs are provided in load module and source forms to illustrate use of the socket and basic C libraries. The ACSHELLO and WHOIS programs distributed as executable programs were created form the BHELLO and BWHOIS sample code. The TTCP program is provided in load module and source forms as an example of how to use the assembler API macro facilities. Any errors encountered by the programs described in this chapter are indicated to the user by error messages. For information about these error messages, see Cisco IOS for S/390 Prefixed Messages and Codes and Cisco IOS for S/390 Unprefixed Messages. These programs might prove valuable to network users. For more information on additional diagnostic commands, see the Cisco IOS for S/390 Customization Guide. These programs are invoked through TSO or a batch job. Instructions for using each program are provided in the following subsections.

Using Cisco IOS for S/390 API and Socket Applications 10-1 ACSHELLO

ACSHELLO The ACSHELLO program acts as a server that can be queried by clients to obtain information about the host on which the ACSHELLO program is executing. This is a nonstandard network service but might be useful to users as a demonstration of the network capabilities. It also provides a good example of the implementation of a network server. The program supports access only via TCP. This program runs until canceled or interrupted, or until an unrecoverable error is detected. ACSHELLO [PORT(TCP_port)] [SYSID(subsystem_ID)]

Syntax Description ACSHELLO Invokes the ACSHELLO program.

PORT(TCP_port) Defines the port the program will use to wait for client requests

SYSID( subsystem_ID ) Lets the user specify the subsystem ID of Cisco IOS for S/390 other than the default used when Cisco IOS for S/390 was installed.

Usage Notes The default port is 43; it is typically used as the WHOIS TCP service. The default subsystem ID is ACSS. Both the PORT and SYSID parameters are optional.

Example The following is sample output of the ACSHELLO program when contacted by a client: ACSHELLO: Server starting at: Wed Feb 07 13:57:27 1990 ACSHELLO: Running on host: MF1.YOURCO.COM ACSHELLO: Host's address is: 129.192.192.129 ACSHELLO: MVS version level is: MVS/SP2.2.0 ACSHELLO: MVS SMF ID is: IPO1 ACSHELLO: CPU ID is: 000130614381 ACSHELLO: Server stopping at: Wed Feb 07 13:57:28 1990

Invoking ACSHELLO Typically this program is used by starting its execution on the mainframe and then querying it using or WHOIS, specifying the port that ACSHELLO is using to listen for requests. If you are using the WHOIS program to query the ACSHELLO server using the default port, invoke the program with this command: WHOIS NAME(ABC) HOST(my_host_name)

10-2 Cisco IOS for S/390 User’s Guide FINGER The FINGER TSO command processor is similar to the UNIX finger command. It obtains information about users of a system. If given only the name of the remote host, FINGER returns information about all users currently logged in on that system. If given the name of a user and the remote host, FINGER returns information about that user. The finger protocol is described in detail in RFC 742. FINGER NAME( lookup_name ) [ LONG ] [ SYSID( subsystem_ID ) ]

Syntax Description FINGER is the command used to obtain information about users logged in to a remote host

NAME( lookup_name ) specifies the user name for which information is requested

LONG provides a more verbose listing of the remote system users' information if the lookup_name specifies only a remote host

SYSID( subsystem_ID ) allows you to specify the subsystem ID of Cisco IOS for S/390 other than the default used when Cisco IOS for S/390 was installed

Usage Notes: The remote host must be running a finger server program for the client to function properly. To obtain information about a single user, lookup_name should be a string in the form of userid @hostname. To obtain information about all users currently logged on to the host, type @hostname. The user ID is converted to lowercase before it is sent to the remote system. The finger server on the remote system should be case insensitive. The NAME(lookup_name) parameter is required. The LONG parameter is optional. The default subsystem ID is ACSS. The SYSID(subsystem_ID) parameter is optional.

Example The following is sample output of the FINGER program: FINGER NAME(gaw@leo) (MF1.YOURCO.COM.) Login name: gaw In real life:..Glen...... Directory:/home/gaw Shell: /bin/csh On since Feb 28 14:53:11 on ttyp2 6 hours 19 minutes Idle Time

Using Cisco IOS for S/390 API and Socket Applications 10-3 TTCP

TTCP The TTCP TSO command processor acts as a data source or sink facility. TTCP is basically a test program for exercising Cisco IOS for S/390 and API functions. TTCP is compatible with the TTCP program available through anonymous FTP for UNIX users. When run in transmit mode, TTCP performs one iteration and exits. When run in receive mode (as a server), TTCP runs until stopped. To stop TTCP when under TSO, use the particular TSO attention key for your terminal. To stop TTCP when running under the TSO TMP in a batch job, use the MVS STOP( P ) command. Any errors encountered by the TTCP program are indicated by error messages. For information about these error messages see Cisco IOS for S/390 Prefixed Messages and Codes. The syntax for the TTCP command is as follows: TTCP[RECEIVE/TRANSMIT] [TCP/UDP] [ASCII/EBCDIC] [ HOST( host_name ) ] [ PORT( port_number ) ] [ SYSID( subsystem_ID ) ] [ BUFLEN( buffer_length ) ] [ BUFNUM( number_of_buffers ) ] [ COUNT( transmit_buffer_count ) ] [ TASKS( number_of_receive_tasks ) ]

Syntax Description: TTCP Name of the command to be executed

RECEIVE Indicates that TTCP should run as a server to receive and discard (sink) all data from any host and port; RECEIVE may also be specified as RECV or RCV

TRANSMIT Indicates that TTCP should run as a client to generate (source) and transmit data to a specified host and port Default is RECEIVE. RECEIVE/TRANSMIT parameter is optional.

TCP Indicates that TCP (Transmission Control Protocol) transport services should be used; TCP may also be specified as COTS

UDP Indicates that UDP (User Datagram Protocol) transport services should be used; UDP may also be specified as CLTS The default is TCP. The transport protocol parameter is optional.

ASCII/EBCDIC In transmit mode, this parameter specifies the character set to use when generating data to be sent. In receive mode, the ASCII/EBCDIC parameter is ignored. ASCII—ASCII character set EBCDIC—EBCDIC character set If not specified in transmit mode, the default is ASCII. The ASCII/EBCDIC parameter is optional

10-4 Cisco IOS for S/390 User’s Guide HOST( host_name ) In transmit mode, the HOST parameter specifies the name of the remote host to which TTCP transmits data. In receive mode, the HOST parameter is ignored.If not specified in transmit mode, the default is 127.0.0.1 (standard loopback Internet address). The HOST parameter is optional.

PORT( port_number ) Port number to use If not specified in transmit mode, the default is 9 (standard TCP/UDP discard port); if not specified in receive mode, the default is 2000. The PORT parameter is optional.

SYSID( subsystem_ID ) Subsystem ID of the Cisco IOS for S/390 address space other than the default used when Cisco IOS for S/390 was installed. SYSID may also be specified as SSN. The default subsystem ID is ACSS The SYSID parameter is optional.

BUFLEN( buffer_length ) Buffer length to be used In transmit mode, COUNT buffers of this length are transmitted. In receive mode, this is the length of each receive buffer. BUFLEN may also be specified as LENGTH If not specified, the default is 1024. The BUFLEN parameter is optional.

BUFNUM( number_of_buffers ) Number of buffers to receive into or transmit from simultaneously; that is, the queue depth of buffering If BUFNUM is greater than 1, there will be transmit or receive overlap, which is generally more efficient. BUFNUM may also be specified as NUMBER or BUFCT. The default is 5. The BUFNUM parameter is optional.

COUNT( transmit_buffer_count ) In transmit mode, COUNT specifies the number of buffers to transmit. COUNT may also be specified as CNT or CT. This parameter is silently ignored in receive mode. If not specified in transmit mode, the default is 1024.

TASKS( number_of_receive_tasks ) In receive mode, specifies the maximum number of receive subtasks that can be active to receive data from remote hosts. This equates to the maximum number of remote hosts that can be transmitting to the TTCP receive server simultaneously. TASKS may also be specified as SUBTASKS. This parameter is silently ignored in transmit mode. The TASK parameter is optional; if not specified in receive mode, the default is 6.

Using Cisco IOS for S/390 API and Socket Applications 10-5 TTCP

Examples • The following is sample output of the TTCP program when in transmit mode: TTCPT: TRANSFER SECONDS 5.5 TSEND'S 1024, TSEND'S/SEC 185.5 BYTES SENT 1048576, BYTES/SEC 189959.4

• The following is sample output of the TTCP program when in receive mode: TTCPR: TRANSFER SECONDS 9.6 TRECV'S 1024, TRECV'S/SEC 34.6 BYTES RECEIVED 048576, BYTES/SEC 35448.8

10-6 Cisco IOS for S/390 User’s Guide WHOIS The WHOIS TSO command processor acts as a WHOIS client and queries a default or user-specified WHOIS server to obtain information about a user-specified name. Information received from the WHOIS server is printed to your terminal. This command can be used to obtain information about hosts and individuals who use the network. Refer to RFC 954 for more information about the WHOIS service. WHOIS NAME(lookup_name) [HOST(server_host)] [ SYSID( subsystem_ID ) ]

Syntax Description WHOIS Invokes the query to obtain information about the specified user.

NAME( lookup_name ) The name to use to obtain information. The lookup_name parameter can be a string of arbitrary characters to pass to the server to obtain information. Space characters should not be embedded in the lookup_name unless the whole parameter is enclosed in double quotes (for example, NAME(YOGI BEAR@JELLYSTONE)). The NAME parameter is required.

HOST( server_host ) Allows the user to specify a WHOIS server host to use instead of the default. The server_host parameter should be the name of the host that provides the WHOIS service. The default host is NIC.DDN.MIL. The HOST parameter is optional.

SYSID( subsystem_ID ) Allows you to specify the subsystem ID of Cisco IOS for S/390 if the default was not used when Cisco IOS for S/390 was installed. The default subsystem ID is ACSS. The SYSID parameter is optional.

Example The following is sample output of the WHOIS program: Wells, David F. (DW140) [email protected] CSDA-East Attn: AMXLS-LILL Letterkenny Army Depot Chambersburg, PA 17201-4180( (717) 267-8100 (DSN) 570-8100 Record last updated on 29-Sep-97

Using Cisco IOS for S/390 API and Socket Applications 10-7 WHOIS

10-8 Cisco IOS for S/390 User’s Guide