Socket Installation and Configuration
Available Languages
Table Of Contents
Socket Installation and Configuration
Socket and C Library Installation
sockcfg Configuration Structure
Compiling the Configuration File
Sample JCL for Compiling Socket Programs
IBM sockcfg Configuration Changes
SAS/C sockcfg Configuration Changes
Compile/Link IBM C/370 C Non-reentrant Program
Compile/Link IBM C/370 C Reentrant Program
Compile/Link SAS/C Non-reentrant Program
Compile/Link SAS/C Reentrant Program
Socket Installation and Configuration
This chapter contains information on installation, configuration, and customization of the API and C socket libraries. It includes these sections:
•
Socket and C Library Installation
Describes the installation of the socket and C libraries.
Describes the configuration file and sockcfg configuration structure. Explains socket life and buffering limits. Also describes compiling the configuration file.
•
Contains sample JCL for compiling and linking the socket configuration file. Includes the IBM and SAS/C sockcfg configuration changes.
Includes sample JCL showing how to compile, link, and execute non-reentrant and reentrant C socket programs using IBM C/370 and SAS/C compilers.
Describes how to change default values within the socket program.
Socket and C Library Installation
This section describes the installation and configuration of the API, socket, and C libraries. For additional explanation of the socket and basic C library functions and features refer to Chapter 1, and Chapter 3, .
The installation of the socket and basic C libraries is accomplished during the SMP installation of the API. The socket and C library object, load, and header files are created by the SMP APPLY process.
Library Data Sets
The socket and C libraries are provided in a number of Partitioned Data Set (PDS) libraries. These libraries are explained in "Header File Library".
This table outlines the socket and C library data sets created during SMP APPLY processing
Table 6-1 Library Data Sets:
Header File Library
The header file library contains the header files you need to include to use the socket library. You must include the correct header files in your C source code before compiling to ensure proper compilation and execution of the socket library. Header files that are no longer necessary are noted but included for backwards compatibility. This table lists and describes the header files:
Table 6-2 Header File Library
acs.h
This header file is no longer required, but is included for backwards compatibility.
api.h
This header file is for use with the C library and when building the socket configuration file. It is not needed to interface to the socket library. It describes the interface to the API when using the C library.
cdefs.h
This header file contains common definitions for compilation of C headers.
ds.h
This header file is for use with the C library. It is not needed to interface to the socket library. It describes the interface to the Network Directory Services (NDS) when using the C library.
ecb.h
This header file is needed when compiling the socket configuration file and is also used internally by the socket library. It is not needed to interface to the socket library.
errno.h
This header file defines the errors that can be returned by the socket library when making requests to it. It also defines GET_ERRNO for backwards compatibility.
ibmc.h
This header file is needed when compiling the socket configuration file and is also used internally by the socket library. It is not needed to interface to the socket library.
icssckt.h
This header file is used for Cisco IOS for S/390 OpenEdition (UNIX System Services) sockets. Read Chapter 7, for more information.
if.h
This header file defines the interface control blocks and ioctl request formats.
if_arp.h
This header file defines the ARP header.
if_ether.h
This header file defines ethernet frame formats.
in.h
This header file defines the constants and structures necessary to interface to a socket in the internet domain.
inet.h
This header file includes in.h and several macro definitions.
ioccom.h
This header file contains ioctl encoding definitions.
ioctl.h
This header file contains standard ioctl definitions for both files and sockets.
ip.h
This header file defines values used by the Internet Protocol (IP) and details the format of an IP header and options associated with IP. The current implementation of the socket library does not let the socket library user access the IP layer; therefore this header file is of little use at this time. This header file will be used in later versions of the socket library that will let the socket library user set IP options.
netdb.h
This header file defines the structures used by the "get" services. It also provides the function prototypes for this family of functions.
param.h
This header file contains various system parameters and macros.
proto.h
This header file is needed when compiling the socket configuration file and is also used internally by the socket library. It is not needed to interface to the socket library.
sasc.h
This header file is needed when compiling the socket configuration file and is also used internally by the socket library. It is not needed to interface to the socket library.
serrno.h
This header file is no longer required and simply includes errno.h and sockcfg.h. It is provided for backwards compatibility.
sockcfg.h
This header file describes the socket configuration structure. It is covered in more detail later in this chapter.
socket.h
This header file defines most of the variables and structures required to interface properly to the socket library. It also provides the function prototypes in ANSI form for those functions that are truly socket functions.
sockio.h
This header file defines socket ioctl values. It includes ioclt.h.
sockvar.h
This header file is needed when compiling the socket configuration file and is also used internally by the socket library. It is not needed to interface to the socket library.
syslog.h
This header file contains header and prototype information for the emulation of a syslog daemon.
systime.h
This header file contains system time structs and defines.
tcp.h
This header file describes those options that can be set for a socket of type SOCK_STREAM.
time.h
This header file contains time structs and defines. A special note is included for SAS/C users concerning the use of the define _USE_SASC_TIME.
types.h
This header file contains various typedefs required for using the socket library. This header file contains most of the BSD types.h with exceptions for items inconsistent with the MVS environment.
uio.h
This header file describes the structures necessary to use vectored buffering of the socket library. Due to ANSI checking, this header file must be included in any header file that includes socket.h.
unistd.h
This header file contains standard UNIX defines minus the standard UNIX function prototypes.
user.h
This header file is needed when compiling the socket configuration file and is also used internally by the socket library. It is not needed to interface to the socket library.
Load Library
The socket and C library routines are provided as a library of load modules. The load library is for use in construction of non-reentrant applications; reentrant program developers should use the object library discussed in the next section. Each compiler has its own load library. When users link their code, they should choose the proper library based on the compiler. The load library should be specified in the SYSLIB concatenation for the link-edit step.
Object Library
To support the creation of reentrant load modules, the socket and C library routines are also supplied as object modules. Each compiler (IBM and SAS) has one object library. When users pre-link their reentrant code, they should choose the proper library based on the compiler used to compile the program. The object library should be specified in the SYSLIB concatenation for the compiler pre-link step.
Sample JCL
Sample JCL for using the socket library is provided in the CNTL data set. The related members are listed below:
Note
Socket Configuration
Once the libraries are created by SMP, the socket library can be configured to meet the needs and dependencies of the site and its users; the C library routines need no customization. The socket library can be customized by each user or by the site system administrator to enforce resource constraints on the users of the socket library. The configuration is accomplished by modifying a configuration file and then compiling it into object module and load module form. The object module is then placed in the data set that has been designated for use as the socket library reentrant object data set. The load module is placed in the data set designated for use as the socket library non-reentrant data set. If you want a custom copy of the configuration, follow the same steps but copy the object and load modules to your private libraries. The source for sockcf.c is in the SAMP data set and the header file (sockcfg.h) is in the H data set.
Configuration File
The configuration file is provided in C source code compilable by either the SAS/C or IBM C compilers. The file's name is sockcf.c and its partner header file, sockcfg.h, describes the structure and default settings of the configuration.
sockcfg Configuration Structure
The configuration is accomplished by changing any configuration options in the sockcf file and then recompiling it. Each variable of the configuration structure is listed below with the allowable range within which it may be set. To change parameters without recompiling the socket file, see t6:
Table 6-3 sockcfg Configuration Options
sockcfg.name [4]
This array contains the characters CNFG. This is used as an eye-catcher and should never be changed during socket library configuration.
sockcfg.length
This integer contains the length in bytes of the configuration structure. Like the previous variable, this one should never be changed by the user during configuration.
sockcfg.nosockets
This variable specifies the maximum number of sockets that each user can use at any one time. This variable can be used to restrict or limit the usage of resources of the socket user. The minimum is 1 and the maximum is 512. The limits placed on this variable are checked (if CONFIGDEBUG is set in sockcfg.flags) at socket library startup time. Other limits may be placed on this variable by setting the sockcfg.maxsocket and sockcfg.minsocket variables. Read "Socket Configuration" for more information.
Default: 20
sockcfg.maxsocket
The maximum number of sockets to let a user specify in the socket configuration. This is only a soft limit and may be varied within the hard limits previously discussed. Its primary use is to check the parameters configured by the user.
Default: 512
sockcfg.minsocket
The minimum number of sockets a user may specify in the socket configuration. Its primary use is to check the parameters configured by the user.
Default: 20
sockcfg.fdsocket
This variable sets the base number that the socket library can use to assign file descriptors to sockets as they are opened. This value must be greater than the maximum file descriptor used by the native C compiler library for files. In this way, the socket library can distinguish between a socket or a file when a function that is supported by both the native C library and the socket library is called. Such functions as read, write, close, and others can be performed by both files and sockets. The current SAS/C compiler uses file descriptors below 40 and the current IBM C compiler does not support operations on file descriptors. The minimum is 0 and the maximum can be calculated by taking the minimum of 512 and sockcfg.maxsocket and subtracting sockcfg.nosockets. For almost all uses the default should suffice. Read "Socket Configuration" for more information.
Default: 64
sockcfg.maxsndbytcnt
This variable sets the maximum transmit byte count that a user may request when setting the send byte buffering characteristics of a socket. This limit cannot exceed the API site default for send byte buffering. The socket library uses the smaller of the two values as the maximum send byte count.
Default: 64000
sockcfg.minsndbytcnt
This variable sets the minimum transmit byte count that users may request when setting the send byte buffering characteristics of a socket. The smallest value allowed is 128.
Default: 128
sockcfg.defsndbytcnt
This variable defines the default send byte buffer allocation of each socket. This value must be between the maximum and minimum values. If USEAPIREQBYTCNTDEFS is set in sockcfg.flags, this variable is ignored and the default value assigned by the API is used.
Default: 32000
sockcfg.maxsndreqcnt
This variable sets the maximum transmit request count that users may request when setting the send request buffering characteristic of a socket. This limit cannot exceed the API site default for send request buffering. The socket library uses the smaller of the two values as the maximum.
Default: 8
sockcfg.minsndreqcnt
This variable sets the minimum transmit request count that users may request when setting the send request buffering characteristics of a socket.
Default: 1
sockcfg.defsndreqcnt
This variable defines the default send request buffer allocation of each socket. This value must be between the maximum and minimum values. If USEAPIREQBYTCNTDEFS is set in sockcfg.flags, this variable is ignored and the default value assigned by the API is used.
Default: 4
sockcfg.maxrcvbytcnt
This variable sets the maximum receive byte count that users may request when setting the receive byte buffering characteristics of a socket. This limit cannot exceed the API site default for receive byte buffering. The socket library uses the smaller of the two values as the maximum.
Default: 64000
sockcfg.minrcvbytcnt
This variable sets the minimum receive byte count that users may request when setting the receive byte buffering characteristics of a socket. The smallest value allowed is 128.
Default: 128
sockcfg.defrcvbytcnt
This variable defines the default receive byte buffer allocation of each socket. This value must be between the maximum and minimum values. If USEAPIREQBYTCNTDEFS is set in sockcfg.flags, this variable is ignored and the default value assigned by the API is used.
Default: 32000
sockcfg.maxrcvreqcnt
This variable sets the maximum receive request count that users may request when setting the receive request buffering characteristics of a socket. This limit cannot exceed the API site default for receive request buffering. The socket library uses the smaller of the two values as the maximum.
Default: 8
sockcfg.minrcvreqcnt
This variable sets the minimum receive request count that users may request when setting the receive request buffering characteristics of a socket.
Default: 1
sockcfg.defrcvreqcnt
This variable defines the default receive request buffer allocation of each socket. This value must be between the maximum and minimum values. If USEAPIREQBYTCNTDEFS is set in sockcfg.flags, this variable is ignored and the default value assigned by the API is used.
Default: 4
sockcfg.subsysid
This character string pointer should point to the four-character string that is the Cisco IOS for S/390 subsystem identifier. This variable is the most common variable that each socket configuration must change. When configuration is to take place, the installer should determine what the subsystem ID is for Cisco IOS for S/390 and then ensure this variable points to this string prior to compiling this module. An improperly specified subsystem ID is detected when the socket library attempts to open a session with the API on behalf of the socket user. This occurs on the first call to the socket function. Read "Customizing Socket Programs" for more information.
Default: ACSS
sockcfg.svcid[2]
This array of pointers should point to the character strings that designate the services provided by the API. The defaults should suffice and, in most instances, the installer need not change these.
Default: for TCP is TCP; for UDP is UDP.
sockcfg.apcbapplid
This variable should point to an application ID. Currently this is not supported and should therefore be set to point to a null string.
sockcfg.apcbpasswd
This variable should point to an application password. Currently, this is not supported and should therefore be set to point to a null string.
sockcfg.apcbflags
This character is used "as is" in the APCB on the application open (AOPEN) call to the assembler API. This value is placed in the apcbflag element of the APCB. For more details on the use of the apcbflag byte, read "apcb".
Default: 0
sockcfg.apcboptc
This character is used "as is" in the APCB on the application open call to the assembler API. This value is placed in the apcboptc element of the APCB. For more details on the use of the apcbflag byte, read "apcb".
Default: 0
sockcfg.errnobase
This integer sets the base value for the socket library to set errno errors. To avoid confusion with the native C library errors, this element should have a value greater than the maximum error value that the native C library would set in errno. The current SAS/C compiler runtime library uses error codes below 50. The current IBM C compiler library does so also.
Default: 100
sockcfg.exitfunc
This variable is a pointer to the C library exit function that is used to set up the shutdown procedure. This should never need to be changed.
Default: texit()
sockcfg.flags
This unsigned long variable is a mask of flag bits that control the characteristics of the socket library. These bits are defined:
31
SIGNALSUPPIf set to 1, user-added signals for SIGIO, SIGURG, and SIGPIPE may be used if they are also defined. This bit is only valid with the SAS/C library.
30
USEAPIREQBYTECNTDEFIf set to 1, the socket library ignores the configuration of the data buffering characteristics and uses the API defaults. The default and recommended setting is to use the API defaults for buffering limits.
29
EXTERRNOMSGSIf set to 1, the perror function of the socket library prints extended error messages when it detects a socket configuration problem or a session initialization problem with the assembler API. When used in conjunction with the CONFIGDEBUG option, this option lets the installer configure the socket library and then run a test program to see if any errors are detected with the configuration. Once the configuration is completed successfully, this flag bit and CONFIGDEBUG bit can be turned off.
0
CONFIGDEBUGIf set to 1, user-added signals for SIGIO, SIGURG, and SIGPIPE may be used if they are also defined. This bit is only valid with the SAS/C library.
Default: 0x80000007 for the SAS/C compiler, 0x80000006 for the IBM C compiler.sockcfg.closetimeout
This variable sets the time in seconds that the socket library is to wait for an orderly release on a SOCK_STREAM socket to occur when the user issues a close library call in blocking mode. This timeout value is not used for closes issued in nonblocking mode so as not to affect the user's environment (rob the user of the one and only timer available). The closetimeout value can be overridden by using the SO_LINGER option of sockets.
Default: 120 seconds (2 minutes)
sockcfg.envrinit
This is a pointer to a function that does C library specific initialization. This should never have to be changed by the installer as the proper routines are included if the correct #defines are turned on at compile time. The routine for the SAS/C library is s0scinit() and for the IBM C library is s0icinit().
sockcfg.envrterm
This is a pointer to a function that does C library specific termination. This should never have to be changed by the installer as the proper routines are included if the correct #defines are turned on at compile time. The routine for the SAS/C library is s0scterm() and for the IBM C library is s0icterm().
sockcfg.comfuncs
This structure of function pointers can be used by the installer to specify the entry point to functions that are common to both the socket library and the native C runtime library. For the SAS/C compiler, the only functions that have duplicate names are read(), write(), and close(). The IBM C compiler has no functions that have duplicate names with functions of the socket library.
sockcfg.comfuncs.read
This is the file descriptor or socket read function.
sockcfg.comfuncs.readv
This is the file descriptor or socket read function using vectored I/O buffering.
sockcfg.comfuncs.write
This is the file descriptor or socket write function.
sockcfg.comfuncs.writev
This is the file descriptor or socket write function using vectored I/O buffering.
sockcfg.comfuncs.ioctl
This is the I/O control function.
sockcfg.comfuncs.fcntl
This is the file descriptor or socket control function.
sockcfg.comfuncs.select
This is the file descriptor or socket I/O synchronous I/O multiplexing function.
sockcfg.comfuncs.close
This is the file descriptor or socket close function.
sockcfg.sigurg
This is the signal number to use for signaling the reception of urgent (OOB) data on a socket. This is only supported with the SAS/C library and the signal used must be one of the user-assigned asynchronous signals.
Default: for the SAS/C compiler is SIGASY6, for the IBM C compiler (for which this option is not supported) is 0.
sockcfg.sigio
This is the signal number to use for signaling the occurrence of a major event on a socket.
Major events include the completion of a connection request done asynchronously, an incoming connection request on a server socket, the abnormal termination of a connection, the reception of an orderly release from the remote endpoint, and the reception of regular data for a socket or any asynchronous error that may occur during the life of a socket. This is only supported with the SAS/C library and the signal used must be one of the user-assigned asynchronous signals.
Default: for the SAS/C compiler is SIGASY7, for the IBM C compiler (for which this option is not supported) is 0.
sockcfg.sigpipe
The signal number to use for signaling an error when a socket that can no longer send any more data has a write request issued to it. This is only supported with the SAS/C library and the signal used must be one of the user-assigned asynchronous signals.
Default: for the SAS/C compiler is SIGASY8, for the IBM C compiler (for which this option is not supported) is 0.
Socket Life
A socket is created by the successful completion of the socket library call. It remains in existence until closed explicitly via the close library call or implicitly via task or address space termination by the socket library user. For sockets of the SOCK_STREAM type that use TCP for transport, close induces TCP to perform an orderly release. This process involves the local endpoint sending a FIN to the remote endpoint and then receiving an ACK for its FIN and a FIN from the remote endpoint. This process may take a great amount of time (as compared to computer instruction execution time).
If the user is running in nonblocking I/O, the close call returns once the local endpoint has scheduled the transmission of the FIN. The socket can no longer be acted on by the socket user but the context related to the socket is still counted against the user's quota of sockets. Not until the orderly release completes does this socket get deallocated and allow for its reuse. If a user does not desire such a feature, the SO_LINGER option may be set so that the socket is freed up possibly prior to the completion of the orderly release. If this option is to be used, the socket user must be prepared for the consequences related to the lack of a proper release occurring at the remote endpoint.
Socket Buffering Limits
The configuration variables listed in "Compiling the Configuration File" define the limits on each socket's receive and transmit buffering abilities. Sockets do not own any data buffers; the underlying assembler API controls these resources. However, sockets can be used to inform the assembler API how much buffering is desired, thus letting the assembler API allocate the appropriate amount of resources to satisfy users' requirements.
Instead of using the API defaults, socket users can have greater restrictions placed on them by configuring the parameters listed in "Socket Configuration" accordingly. In all cases, socket users are not able to acquire more than the API maximums. If the defaults provided in the configuration are not enough to satisfy the socket users, they may request more by using the setsockopt library call.
Receive and transmit buffering are totally independent of one another. Buffering limits consist of these elements:
•
•
This is much like UNIX sockets, which provide a certain number of bytes for buffering while at the same time limiting the number of mbufs a user can tie up at a given time.
We recommend that the USEAPIREQBYTECNTDEFS be set on in sockcfg.flags; this provides socket users with the default site parameters for API buffering characteristics. The only time this flag should be turned off is when resource restrictions are to be placed on socket library users.
Compiling the Configuration File
Once the configuration file has been modified for site dependencies, it must be properly compiled. Sample JCL is provided in the CNTL data set to accomplish this task. The name of the member is UMODCFGI for IBM C/370 users and UMODCFGS for SAS/C users. This JCL creates the sockcf module for both reentrant and non-reentrant usage. The most important part of this task is to ensure the proper PARMs are used at compilation time. These are the PARMs of importance:
Table 6-4 Socket Configuration File Parameters
The PARM field in each sample JCL is shipped with the proper configuration. This table outlines the necessary PARMs required to build each socket configuration module type:
SAS/C
non-reentrant
X
SAS/C
reentrant
X
X
IBM C
non-reentrant
X
IBM C
reentrant
X
X
Note
These variables are resolved when the user program is linked with the socket library.
You should run an SMP/E APPLY CHECK against any USERMOD that you are trying to install as there may be additional PREs on your system that are not accounted for. Once you gather this information, add the SYSMOD list(s) to the ++PRE(xxxxxx) statement. Then SMP/E REJECT the USERMOD to remove the invalid entry from the SMP/E CSI. You will then be able to RECEIVE/APPLY the USERMOD with success.
Sample JCL for Compiling Socket Programs
This section contains sample JCL for compiling and linking the socket configuration file. It includes examples for users of IBM C/370 and SAS/C compilers.
Note
IBM sockcfg Configuration Changes
//UMODCFGI JOB//*//* SAMPLE SMP/E JCL TO RECEIVE AND APPLY A USERMOD TO//* INSTALL A CUSTOMIZED VERSION OF SOCKCF SOURCE//* CONTAINING C SOCKET CONFIGURATION PARAMETERS FOR//* IBM C/370 USERS.//*//* EDIT THE JOB JCL STATEMENT AND VERIFY THAT THE DATA SET//* NAMES REFERENCED BELOW MATCH THE NAMES THAT YOU SELECTED//* FOR THE TCP/IP TARGET DATA SETS (DSN'S TO BE VERIFIED//* ARE MARKED BELOW WITH "<=== VERIFY ..."). THIS JOB//* ASSUMES THAT THE STANDARD IBM 370 EDCC JCL PROCEDURES IS//* AVAILABLE IN YOUR INSTALLATION'S PROCLIB(S).//*//* GLOBALLY CHANGE THE FOLLOWING STRINGS TO CORRECTLY//* REFLECT TARGET DATASETS AND SMPE FMID.//*//* 'TRGINDX' < SMPE TARGET DATASETS HIGH LEVEL QUALIFIER//* XXX < SMPE FMID IDENTIFING MVS TCP/IP FMID//*//* STEP 1: COMPILE THE NON-REENTRANT VERSION OF SOCKCF//* TO CREATE OBJECT WHICH WILL BE PASSED TO THE//* SUBSEQUENT SMP/E USERMOD RECEIVE/APPLY STEP.//*//CNORENT EXEC EDCC,CPARM='DEF(IBMC),SEQUENCE(73,*)',// INFILE='TRGINDX.SAMP(SOCKCF)' <=== VERIFY DSNAME//COMPILE.SYSLIB DD// DD DISP=SHR,DSN=TRGINDX.H <=== VERIFY DSNAME//COMPILE.SYSLIN DD DISP=(NEW,PASS),DSN=&&COBJ(SOCKCFI),// UNIT=VIO,SPACE=(3200,(10,10,1)),// DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)//*//* STEP 2: COMPILE THE REENTRANT VERSION OF SOCKCF//* TO CREATE OBJECT WHICH WILL BE PASSED TO THE//* SUBSEQUENT SMP/E USERMOD RECEIVE/APPLY STEP.//*//CRENT EXEC EDCC,CPARM='DEF(IBMC),RENT,SEQUENCE(73,*)',// INFILE='TRGINDX.SAMP(SOCKCF)' <=== VERIFY DSNAME//COMPILE.SYSLIB DD// DD DISP=SHR,DSN=TRGINDX.H <=== VERIFY DSNAME//COMPILE.SYSLIN DD DISP=(OLD,PASS),DSN=&&COBJ(SOCKCFIR)//*//* STEP 3: EXECUTE SMP/E TO INSTALL A USERMOD TO UPDATE//* THE REENTRANT AND NON-REENTRANT VERSIONS OF//* SOCKCF FOR IBM C/370 USERS.//*//* CHANGE 'XXX' TO THE CORRECT MVS TCP/IP FMID.//*//SMPE EXEC PGM=GIMSMP,REGION=4096K,TIME=960,// PARM='CSI=SMPINDX.CSI,PROCESS=WAIT'//SMPHOLD DD DUMMY//SMPLOG DD DSN=SMPINDX.SMPLOG,DISP=MOD//SMPOUT DD SYSOUT=HOLDCL//COBJ DD DISP=(OLD,DELETE),DSN=&&COBJ//SMPPTFIN DD *++ USERMOD (MU0CFGI) .++ VER (Z038)FMID(API0XXX) /* CHANGE TO YOUR MVS TCP/IP FMID */ .++ USER2 (SOCKCFIR) TXLIB(COBJ) DISTLIB(AAPICIRO) .++ MOD (SOCKCFI) TXLIB(COBJ) DISTLIB(AAPICL) ./*//SMPCNTL DD *SET BDY(GLOBAL) .RECEIVE S(MU0CFGI) .SET BDY(TCPTZN) .APPLY S(MU0CFGI) ./*SAS/C sockcfg Configuration Changes
//UMODCFGS JOB//*//* SAMPLE SMP/E JCL TO RECEIVE AND APPLY A USERMOD TO//* INSTALL A CUSTOMIZED VERSION OF SOCKCF SOURCE//* CONTAINING C SOCKET CONFIGURATION PARAMETERS FOR//* SAS SAS/C USERS.//*//* EDIT THE JOB JCL STATEMENT AND VERIFY THAT THE DATA SET//* NAMES REFERENCED BELOW MATCH THE NAMES THAT YOU SELECTED//* FOR THE MVS TCP/IP TARGET DATA SETS (DSN'S TO BE//* VERIFIED ARE MARKED BELOW WITH "<=== VERIFY ..."). THIS//* JOB ASSUMES THAT THE STANDARD SAS/C LC370C JCL PROCEDURE//* IS AVAILABLE IN YOUR INSTALLATION'S PROCLIB(S).//*//* GLOBALLY CHANGE THE FOLLOWING STRINGS TO CORRECTLY//* REFLECT TARGET DATASETS AND SMPE FMID.//*//* 'TRGINDX' < SMPE TARGET DATASETS HIGH LEVEL QUALIFIER//* XXX < SMPE FMID IDENTIFING MVS TCP/IP FMID//*//* STEP 1: COMPILE THE NON-REENTRANT VERSION OF SOCKCF//* TO CREATE OBJECT WHICH WILL BE PASSED TO THE//* SUBSEQUENT SMP/E USERMOD RECEIVE/APPLY STEP.//*//CNORENT EXEC LC370C,PARM.C='DEF(SASC)'//C.SYSLIN DD DISP=(NEW,PASS),DSN=&&COBJ(SOCKCFS),// UNIT=VIO,SPACE=(3200,(10,10,1))//C.SYSLIB DD DISP=SHR,DSN=TRGINDX.H <=== VERIFY DSNAME// DD DISP=SHR,DSN=SASC.MACLIBC <=== VERIFY DSNAME//C.SYSIN DD DISP=SHR,// DSN=TRGINDX.SAMP(SOCKCF) <=== VERIFY DSNAME//*//* STEP 2: COMPILE THE REENTRANT VERSION OF SOCKCF TO//* CREATE OBJECT WHICH WILL BE PASSED TO THE//* SUBSEQUENT SMP/E USERMOD RECEIVE/APPLY STEP.//*//CRENT EXEC LC370C,PARM.C='DEF(SASC),RENT'//C.SYSLIN DD DISP=(OLD,PASS),DSN=&&COBJ(SOCKCFSR)//C.SYSLIB DD DISP=SHR,DSN=TRGINDX.H <=== VERIFY DSNAME// DD DISP=SHR,DSN=SASC.MACLIBC <=== VERIFY DSNAME//C.SYSIN DD DISP=SHR,// DSN=TRGINDX.SAMP(SOCKCF) <=== VERIFY DSNAME//*//* STEP 3: EXECUTE SMP/E TO INSTALL A USERMOD TO UPDATE//* THE REENTRANT AND NON-REENTRANT VERSIONS OF//* SOCKCFG FOR SAS/C USERS.//*//* CHANGE THE 'XXX' TO THE CORRECT MVS TCP/IP FMID.//*//SMPE EXEC PGM=GIMSMP,REGION=4096K,TIME=960,// PARM='CSI=SMPINDX.CSI,PROCESS=WAIT'//SMPHOLD DD DUMMY//SMPLOG DD DSN=SMPINDX.SMPLOG,DISP=MOD//SMPOUT DD SYSOUT=HOLDCL//COBJ DD DISP=(OLD,DELETE),DSN=&&COBJ//SMPPTFIN DD *++ USERMOD (MU0CFGS) .++ VER (Z038)FMID(API0XXX) /* CHANGE TO YOUR MVS TCP/IP FMID */ .++ USER1 (SOCKCFSR) TXLIB(COBJ) DISTLIB(AAPICSRO) .++ MOD (SOCKCFS) TXLIB(COBJ) DISTLIB(AAPICL) ./*//SMPCNTL DD *SET BDY(GLOBAL) .RECEIVE S(MU0CFGS) .SET BDY(TCPTZN) .APPLY S(MU0CFGS) ./*Using Socket Libraries
After the socket library has been properly installed, it is ready for use. When writing code to use the socket library, make sure the proper header files are included in each source file using socket structures, defines, or function calls. Once the code is written, concatenate the socket library header data set to their SYSLIB concatenation for the compile step.
For non-reentrant users, concatenate the proper socket library load data set to the SYSLIB concatenation for the link-edit step. For reentrant users, concatenate the proper socket library object data set to the SYSLIB concatenation and include the proper modules.
The sample JCLs show how to compile, link, and execute non-reentrant and reentrant C socket programs using the IBM C/370 and SAS/C compilers.
Compile/Link IBM C/370 C Non-reentrant Program
This JCL is for the C/370 version of the compiler. If you are using the AD/Cycle compiler, replace this line (shown in bold in the JCL):
// DD DISP=SHR,DSN=&VSCCHD&CVER&EDCHDRSwith this line:
// DD DISP=SHR,DSN=&LNGPRFX..SEDCDHDRThe AD/Cycle compiler does not use the first DD statement shown after the LKED.SYSLIB DD in this JCL example. See sidebar comment.
//CLGIBMC JOB//*//* SAMPLE JCL TO COMPILE, LINK, AND EXECUTE A NONREENTRANT//* USER PROGRAM USING THE TCP/API C SOCKET LIBRARIES//* AND THE IBM C/370 C COMPILER.//*//* EDIT THE JOB JCL STATEMENT, VERIFY THE DATA SET NAME(S)//* OF THE USER'S DATA SETS, AND VERIFY THAT THE DATA SET//* NAMES REFERENCED BELOW MATCH THE NAMES THAT YOU SELECTED//* FOR THE TCP/IP TARGET DATA SETS (DSN'S TO BE VERIFIED//* ARE MARKED BELOW WITH "<=== VERIFY ..."). THIS JOB//* ASSUMES THAT THE STANDARD IBM C/370 EDCCLG JCL PROCEDURE//* IS AVAILABLE IN YOUR INSTALLATION'S PROCLIB(S).//*//CLGNRENT EXEC EDCCLG,// INFILE='USER.C(CPROG)', <=== VERIFY DSNAME// CPARM='DEF(IBMC),NORENT',// GPARM='PROGRAM PARAMETERS <=== VERIFY PARAMETERS//*//* INCLUDE THE TCP/API SOCKET INCLUDE (.H) DATA SET IN THE//* COMPILER SYSLIB CONCATENATION.//*//COMPILE.SYSLIB DD DISP=SHR,DSN=TRGINDX.H <=== VERIFY DSNAME// DD DISP=SHR,DSN=&VSCCHD&CVER&EDCHDRS//*//* INCLUDE THE TCP/API SOCKET SUBROUTINE LIBRARY DATA SET//* IN THE LINKAGE EDITOR SYSLIB CONCATENATION.//*//LKED.SYSLIB DD// DD// DD DISP=SHR,DSN=TRGINDX.CILIB <=== VERIFY DSNAME//*//LKED.SYSIN DD DUMMY,DCB=(LRECL=80,RECFM=FB,BLKSIZE=3120)Compile/Link IBM C/370 C Reentrant Program
This JCL is for the C/370 version of the compiler. If you are using the Ad/Cycle compiler, replace the following line (shown in bold in the JCL):
// DD DISP=SHR,DSN=&VSCCHD&CVER&EDCHDRSwith this line:
// DD DISP=SHR,DSN=&LNGPRFX..SEDCDHDR//CLGIBMCR JOB//*//* SAMPLE JCL TO COMPILE, LINK, AND EXECUTE A REENTRANT//* USER PROGRAM USING THE TCP/API C SOCKET LIBRARIES//* AND THE IBM C/370 C COMPILER.//*//* EDIT THE JOB JCL STATEMENT, VERIFY THE DATA SET NAME(S)//* OF THE USER'S DATA SETS, AND VERIFY THAT THE DATA SET//* NAMES REFERENCED BELOW MATCH THE NAMES THAT YOU SELECTED//* FOR THE TCP/IP TARGET DATA SETS (DSN'S TO BE VERIFIED//* ARE MARKED BELOW WITH "<=== VERIFY ..."). THIS JOB//* ASSUMES THE STANDARD IBM C/370 EDCCPLG JCL PROCEDURE IS//* AVAILABLE IN YOUR INSTALLATION'S PROCLIB(S).////CLGRENT EXEC EDCCPLG,// INFILE='USER.C(CPROG)', <=== VERIFY DSNAME// CPARM='RENT,DEF(IBMC)',// GPARM='PROGRAM PARAMETERS' <=== VERIFY PARAMETERS//*//* INCLUDE THE TCP/API SOCKET INCLUDE (.H) DATA SET IN THE//* COMPILER SYSLIB CONCATENATION.//*//COMPILE.SYSLI DD DISP=SHR,DSN=TRGINDX.H <=== VERIFY DSNAME// DD DISP=SHR,DSN=&VSCCHD&CVER&EDCHDRS//*//* INCLUDE THE TCP/API SOCKET SUBROUTINE OBJECT LIBRARY//* DATA SET IN THE PREPROCESSOR SYSLIB CONCATENATION.//*//PLKED.SYSLIB DD DISP=SHR,// DSN=TRGINDX.CIROBJ <=== VERIFY DSNAME//PLKED.SYSIN DD DSN=*.COMPILE.SYSLIN,DISP=(OLD,DELETE)// DD *INCLUDE SYSLIB(S0SKCF)INCLUDE SYSLIB(S0INTR)ENTRY CEESTART/*//Compile/Link SAS/C Non-reentrant Program
//CLGSASC JOB//*//* SAMPLE JCL TO COMPILE, LINK, AND EXECUTE A NONREENTRANT//* USER PROGRAM USING THE TCP/API C SOCKET LIBRARIES//* AND THE SAS/C C COMPILER. THIS SAMPLE WILL//* WORK WITH SAS/C 4.50, 5.00, 5.01 AND 5.50C.//*//* EDIT THE JOB JCL STATEMENT, VERIFY THE DATA SET NAME(S)//* OF THE USER'S DATA SETS, AND VERIFY THAT THE DATA SET//* NAMES REFERENCED BELOW MATCH THE NAMES THAT YOU SELECTED//* FOR THE TCP/IP TARGET DATA SETS (DSN'S TO BE VERIFIED//* ARE MARKED BELOW WITH "<=== VERIFY ..."). THIS JOB//* ASSUMES THAT THE STANDARD SAS/C LC370CLG JCL PROCEDURE//* IS AVAILABLE IN YOUR INSTALLATION'S PROCLIB(S).//*//CLNORENT EXEC LC370CLG,// PARM.C='DEF(SASC),NORENT',// PARM.GO='PROGRAM PARAMETERS' <=== VERIFY PARAMETERS//*//* TCP/IP INCLUDE FILE DATA SET MUST PRECEDE SAS/C//* DATA SET.//*//C.SYSLIB DD DISP=SHR,DSN=TRGINDX.H <=== VERIFY DSNAME// DD DISP=SHR,DSN=&MACLIB//C.SYSIN DD DISP=SHR,// DSN=USER.C(CPROG) <=== VERIFY DSNAME////* TCP/IP OBJECT SYSLIB DATA SET MUST PRECEDE SAS/C//* DATA SETS.//*//LKED.SYSLIB DD DISP=SHR,// DSN=TRGINDX.CSLIB<=== VERIFY DSNAME// DD DISP=SHR,DSN=SASC.&ENV.LIB <=== VERIFY DSNAME// DD DISP=SHR,DSN=&SYSLIB// DD DISP=SHR,DSN=&CALLLIB//LKED.SYSIN DD DUMMY,DCB=(LRECL=80,RECFM=FB,BLKSIZE=3120)Compile/Link SAS/C Reentrant Program
//CLGSASCR JOB//*//* SAMPLE JCL TO COMPILE, LINK, AND EXECUTE A REENTRANT C//* PROGRAM USING THE TCP/API C SOCKET LIBRARIES AND THE//* SAS/C C COMPILER. THIS SAMPLE WILL WORK WITH SAC/C 4.50,//* 5.00, 5.01 AND 5.50C.//*//* EDIT THE JOB JCL STATEMENT, VERIFY THE DATA SET NAME(S)//* OF THE USER'S DATA SETS, AND VERIFY THAT THE DATA SET//* NAMES REFERENCED BELOW MATCH THE NAMES THAT YOU SELECTED//* FOR THE TCP/IP TARGET DATA SETS (DSN'S TO BE VERIFIED//* ARE MARKED BELOW WITH "<=== VERIFY ..."). THIS JOB//* ASSUMES THAT THE STANDARD SAS/C LC370C AND LC370LRG JCL//* PROCEDURES ARE AVAILABLE IN YOUR INSTALLATION'S//* PROCLIB(S).//*//* STEP 1: COMPILE USER PROGRAM REENTRANTLY.//*//CCRENT EXEC LC370C,// PARM.C='RENT,DEF(SASC)'//*//* TCP/IP INCLUDE FILE DATA SET MUST PRECEDE SAS/C//* DATA SET.//*//C.SYSLIB DD DISP=SHR,DSN=TRGINDX.H <=== VERIFY DSNAME// DD DISP=SHR,DSN=&MACLIB//C.SYSIN DD DISP=SHR,// DSN=USER.C(CPROG) <=== VERIFY DSNAME//*//* STEP 2: LINK USER PROGRAM USING SAS/C CLINK//* PREPROCESSOR AND THEN EXECUTE.//*//LKRENT EXEC LC370LRG,PARM.LKED='LIST,MAP,RENT',// PARM.GO='PROGRAM PARAMETERS' <=== VERIFY PARAMETERS//*//* TCP/IP OBJECT SYSLIB DATA SET MUST PRECEDE SAS/C//* DATA SETS.//*//LKED.SYSLIB DD DISP=SHR,DSN=TRGINDX.CSROBJ <=== VERIFY DSNAME// DD DDNAME=AR#&ALLRES// DD DISP=SHR,DSN=SASC.&ENV.OBJ <=== VERIFY DSNAME// DD DISP=SHR,DSN=&SYSLIB// DD DISP=SHR,DSN=&CALLLIB//LKED.SYSIN DD DISP=(OLD,DELETE),DSN=*.CCRENT.C.SYSLIN// DD *INCLUDE SYSLIB(S0SKCF)INCLUDE SYSLIB(S0INTR)ENTRY MAIN/*//Customizing Socket Programs
Socket programs can be easily customized without the need to change and recompile the sockcf file. This leaves the sockcf object file untouched for use by other socket applications, but allows individual versatility for testing and customizing within the program itself. The fields of the sockcfg struct can be changed by including the header file serrno.h or sockcfg.h in your source program and setting the desired fields in the externally declared variable s0skcfg.
Note
Read "Using Socket Libraries", which describes the fields of the sockcfg struct, before changing the default values.
Changing Values
These statements demonstrate how these values can be changed within the socket program:
#include <sockcfg.h>.. ( other include files ).main(){s0skcfg.subsysid = "ABCD"; /* set subsysid */s0skcfg.apcboptc = APCBOTRC; /* set api trace on */( rest of program )}
FeedbackContact Cisco
- Open a Support Case
- (Requires a Cisco Service Contract)