Basic client-server routines

Open communication with a remote node

CALL CZOPEN (SERVICE,HOST,IRC*)

SERVICE

Character variable specifying the name of the service required, e.g. ZSERV

HOST

Character variable specifying the name of the remote host.

IRC

Integer variable in which the return code is returned.

This routine opens a connection with a remote node. A new process is automatically created on the specified node using the username and password that are prompted for at the terminal.

When TCPAW is used as the network layer, usernames and passwords may also be given in a .netrc file in the user's home directory (Unix systems). In the case of VAX/VMS systems, the name of this file is .ftplogin;. For VM/CMS systems running the C version of TCPAW, this file is DOT NETRC A0. For a description of the format of these files, see page .        

In the case of VM systems, the virtual machine of the specified user is autologged. This requires that the user in question is not currently logged on.

Example of using the CZOPEN routine

      CALL CZOPEN('ZSERV','CERNVM',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from CZOPEN

To select DECnet instead of TCP/IP as the communications protocol, the variable IPROT in the sequence CZSOCK should be set to 1.

Example of using DECnet as the communications protocal

+CDE,CZSOCK. From CSPACK PAM
     IPROT = 1
     CALL CZOPEN('ZSERV','VXCRNA',IRC)

When using DECnet as the communications protocol, username and password prompting only occurs for interactive sessions. For other sessions, a server is started using the standard DECnet techniques, i.e. using a PROXY account if one exists, or else the default DECnet account.

To disable username and password prompting for interactive sessions, set the logical name CZPROXY to TRUE, e.g.

Turning off username prompting for DECnet connections

DEFINE CZPROXY TRUE

Close communication with the current remote node

CALL CZCLOS (IRC*)

IRC

Integer variable in which the return code is returned.

This routine closes the connection with the current remote node. The process on the remote node is automatically terminated. The current remote node is the one specified in the last call to CZOPEN, or set by the routine CZSWAP.

Example of using the CZCLOS routine

      CALL CZCLOS(IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from CZCLOS

Switch communication to another node

CALL CZSWAP (NODE,LUN,IRC*)

NODE

Character variable specifying the node name to which communication should be swapped.

LUN

Integer variable specifying the logical unit associated with the remote node.

IRC

Integer variable in which the return code is returned.

This routine changes the current node to that associated with the specified logical unit or nodename. If the nodename is non-blank, communication is swapped to the specified node. If the nodename is blank, communication is swapped to the node associated to LUN (e.g. from a call to XZOPEN, see on Page ). This routine is called automatically by the routines of the XZ package and need normally not be called by a user.

Example of using the CZSWAP routine

      CALL CZSWAP(' ',77,IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from CZSWAP

Return real time elapsed since last call

CALL CZRTIM (ELAPSED*)

ELAPSED

Character variable in which the elpased time is returned in the format HH:MM:SS.

The CZRTIM routine is used by the XZGET/PUT routines if the option S is specified in order to print statistics on data transfer rates. This routine must always be called twice: once to start the timer and a second time to return the elapsed time.

Example of using the CZRTIM routine

*
*     Start timer
*
      CALL CZRTIM(ELAPSD)
*     Work a little
*     ...
*
*     Get elapsed time since last call
      CALL CZRTIM(ELAPSD)

Send text string to current remote node

CALL CZPUTA (STRING,IRC*)

STRING

Character variable containing the data to be sent to the remote node.

IRC

Integer variable in which the return code is returned.

This routine sends a text string to the remote server.

Example of using the CZPUTA routine

*
*     Extract from the ZFTP routine ZFTPCD (action routine for
*     the CD command.
*
      CALL CZPUTA('XZIO :CD '//PATH(1:LPATH)',IRC)
      IF(IRC.NE.0) PRINT *,'Return code ',IRC,' from CZPUTA

Read text string from remote server

CALL CZGETA (STRING,IRC*)

STRING

Character variable in which the data read from the remote server is returned.

IRC

Integer variable in which the return code is returned.

This routine gets a text string from the remote server. An example of its use in the ZFTP program is shown on the following page.

Example of using the CZGETA routine

*
*     Sequence CZMESS from CSPACK - this sequence is used by the
*     various XZ routines to process server messages.
*
+KEEP,CZMESS.
*
*     Process server messages
*
10    CONTINUE
      CALL CZGETA(CHMAIL,ISTAT)
      LCH = LENOCC(CHMAIL)
      IF(CHMAIL(1:1).EQ.'0') THEN
*
*        Nop
*
      ELSEIF(CHMAIL(1:1).EQ.'1') THEN
         PRINT *,CHMAIL(2:LCH)
      ELSEIF(CHMAIL(1:1).EQ.'2') THEN
         PRINT *,CHMAIL(2:LCH)
         GOTO 10
      ELSEIF(CHMAIL(1:1).EQ.'3') THEN
         PRINT *,CHMAIL(2:LCH)
         IQUEST(1) = 1
         IRC       = 1
      ELSEIF(CHMAIL(1:1).EQ.'E') THEN
         IQUEST(1) = -1
         IRC       = -1
      ELSEIF(CHMAIL(1:1).EQ.'V') THEN
*
*        Number of bytes read from a variable length read
*
         READ(CHMAIL(2:11),'(I10)') NGOT
         GOTO 10
      ELSE
         PRINT *,'Unknown server message ',CHMAIL
         IQUEST(1) = 1
         IRC       = 1
      ENDIF
*

Send character array to remote server process

CALL CZPUTC (NCHAR,IRC*)

NCHAR

Integer variable giving the number of characters to be sent. The data is in the common block /CZBUFC/ in the character variable CHBUF.

IRC

Integer variable in which the return code is returned.

This routine sends a character string to the remote server.

Example of using the CZPUTC routine

      CALL CZPUTC(NTOT,ISTAT)
      IF(ISTAT.NE.0)GO TO 99

Get character array from remote server process

CALL CZGETC (NCHAR,IRC*)

NCHAR

Integer variable giving the number of characters to be sent. The data is in the common block /CZBUFC/ in the character variable CHBUF.

IRC

Integer variable in which the return code is returned.

This routine reads a character string from the remote server.

Example of using the CZGETC routine

      CALL CZGETC(NTOT,ISTAT)
      IF(ISTAT.NE.0)GO TO 99

Transfer data between client and server

CALL CZTCP (IBUFF,ICONTR)

IBUFF

Array containing hollerith or binary data to be sent to the server or received from the server depending on the ICONTR vector.

ICONTR

Integer vector of length 2 to determine mode of operation. ICONTR(1) = IMODE, ICONTR(2) = NBYTES

This routine sends or receives data to/from the remote server.

IMODE = 0: receive binary

IMODE = 1: send binary
IMODE = 2: receive character data
IMODE = 3: send character data

Example of using the CZTCP routine

*
*     Send the data
*
            ICONT(1) = 1
            LBUF     = NWORDS
            CALL CZTCP(IBUFF,ICONT)
            ENDIF