If your system supports DECnet facilities, and your computer is one of the nodes in a DECnet network, you can communicate with other nodes in the network by means of standard PL/I I/O statements. These statements provide two distinct types of network operations:

• Remote file access lets you read and write files on a remote node as if the files were on your local system.
• Task-to-task communication lets you exchange data directly with a job that is being executed at a remote location.

Examples of both remote file access and task-to-task communication using PL/I statements are given in this chapter. For details on using DECnet, see the DECnet-VAX or DECnet/OSI documentation.

14.1 Remote File Access

To access a file on a remote system, you include the node name in the file specification of the external file you identify for the execution of the program. For example:

BOSTON::DBA0:[MALCOLM]TEMPS.TST

This file specification identifies the file TEMPS.TST in the directory [MALCOLM] on the device DBA0: on the node BOSTON.

You can specify a node name in a file specification in either of the following contexts:

• In the file specification in the TITLE option of an OPEN statement
• In the equivalence name you assign to a logical name before running a program that refers to a file by logical name

For example:

OPEN FILE (NETFILE) SEQUENTIAL INPUT RECORD TITLE ('TULSA::DBB0:[MALCOLM]PLITEST.DAT');

This OPEN statement specifies the name of a file to be read from the node named TULSA.

If no file specification is present in the TITLE option, or if the TITLE option specifies a logical name, you can define a remote file. For example:

OPEN FILE(INFILE) INPUT RECORD SEQUENTIAL;

This OPEN statement refers to the logical name INFILE. The following DEFINE command equates this logical name with a remote file:

$ DEFINE INFILE TULSA::DBB0:[MALCOLM]PL1TEST.DAT

When the OPEN statement is executed, the run-time system associates the remote file with the PL/I file INFILE.

When you run a program that modifies a file on a remote node in a protected account, the file specification must contain an access control string. Each Hewlett Packard operating system defines the format of an access control string. For an OpenVMS system, you specify the user name and password of the account whose file you are modifying. For example:

$ DEFINE INFILE - $_TULSA""MALCOLM YES"""::DBB0:[ENERGY]PL1TEST.DAT"

The user name MALCOLM and the password for this account (YES) are enclosed in quotation marks following the node name in the file specification. The extra quotation marks are required because the DCL command interpreter removes single pairs of quotation marks from lines. On the system at the node TULSA, the user MALCOLM must have access privileges to the account ENERGY.

The following file-system functions are not available for processing remote files: keyed statements (DELETE, WRITE, REWRITE FILE_ID_TO, FILE_ID_FROM, RECORD_ID_TO, and RECORD_ID_FROM) cannot be followed by a sequential operation; that is, an operation that does not specify a key.

14.2 Task-to-Task Communication

Network task-to-task communication lets a program running on one network node interact with a program running on another network node. The interaction is accomplished with PL/I I/O statements, but network connections themselves are transparent to the cooperating programs.

PL/I programs at remote locations can communicate over the network by the following mechanism:

1. The program that initiates the communication is called the source task. It requests a network connection to a target task by specifying a task name in a file specification that contains a node name. This OPEN statement initiates the request and associates a PL/I file with a network logical link created by DECnet. For example:

   OPEN FILE (TASKFILE) RECORD OUTPUT TITLE ('HSTN"MALCOLM YES"::"TASK=LOGGER" ');

   
   This OPEN statement initiates task-to-task communication with the target node by specifying the task name LOGGER. The network program uses the default directory of user MALCOLM to locate the command file LOGGER.COM on the remote target node.

2. DECnet locates the command file LOGGER.COM on the remote node specified in the OPEN statement. The name of the command file is specified by the task specification string, TASK=LOGGER. DECnet submits this command file for execution by the remote system. When the OPEN statement completes, communication between the two tasks can begin.
3. The command file LOGGER.COM must contain the command necessary to initiate the execution of the cooperating program, COPYTASK.

   $ RUN COPYTASK

   
   The network program submits the specified command file to the batch job queue on the target system.

4. The cooperating target task must complete the connection to the source task by executing an OPEN statement to open the file SYS$NET.

   OPEN FILE (NETFILE) RECORD SEQUENTIAL INPUT TITLE ('SYS$NET');

   
   SYS$NET is a logical name assigned by DECnet to the network job that identifies the source task's node and process.

5. After the logical link is established, the cooperating programs, or tasks, read and write data using the PL/I files associated with the logical link.
6. When either program executes a CLOSE statement for the file, the logical link is broken and an end-of-file record is written to the cooperating task.

Examples 14-1 and 14-2 illustrate PL/I programs that communicate across the network using synchronous I/O. The following notes are keyed to Example 14-1:

1. The procedure SOURCE_TASK is the program that initiates the request.
2. The UNDEFINEDFILE condition will be signaled if any error occurs that is associated with the logical link or connection. In the ON-unit, the procedure uses the ONCODE built-in function to obtain the error code, display the status value, and stop the program.
3. The OPEN statement associates the PL/I file TASKNAME with the task named LOGGER on the node named BOSTON. The network program uses the default directory for the account BEANS on the node and locates the command file LOGGER.COM. The file LOGGER.COM contains this command:

   $ RUN TARGET

4. The procedure writes three messages from the structure TASK_MESSAGE. The first field is a binary value, and the second field a character-string text.
5. When the three messages have been written, the CLOSE statement closes the file to terminate the network connection.

Example 14-1 A PL/I Network Source Task

SOURCE_TASK: PROCEDURE; /* (1) */ DECLARE TASKNAME FILE; DECLARE 1 TASK_MESSAGE, 2 NUMBER FIXED BINARY(31), 2 TEXT CHARACTER(40) VARYING; ON UNDEFINEDFILE(TASKNAME) BEGIN; /* (2) */ PUT SKIP LIST('File error',ONCODE()); STOP; END; OPEN FILE(TASKNAME) SEQUENTIAL OUTPUT RECORD /* (3) */ TITLE('BOSTON"BEANS BAKED"::"TASK=LOGGER"'); NUMBER = 1; /* (4) */ TEXT = 'first message'; WRITE FILE (TASKNAME) FROM (TASK_MESSAGE); NUMBER = 2; TEXT = 'second message'; WRITE FILE (TASKNAME) FROM (TASK_MESSAGE); NUMBER = 3; TEXT = 'third and last message'; WRITE FILE(TASKNAME) FROM (TASK_MESSAGE); CLOSE FILE(TASKNAME); /* (5) */ RETURN; END;

The following notes are keyed to Example 14-2:

1. The image file TARGET.EXE contains the compiled and linked code for the procedure TARGET_TASK. The declarations in the procedure TARGET_TASK include the files INFILE and OUTFILE, a structure into which messages will be read across the logical link, and a message field from which data will be written to the output file.
2. The procedure establishes an UNDEFINEDFILE ON-unit for any error conditions that occur in creating the logical link; at the label FILE_ERROR, the status code is reported and the procedure exits.
3. The ENDFILE condition provides for a normal termination of the logical link. When the program SOURCE_TASK closes the file TASKNAME, an end-of-file condition is returned on the next read attempted in TARGET_TASK.
4. The first OPEN statement opens the file SYS$NET; if the file is opened successfully, the network connection is established. The second OPEN statement opens the file TASK.DAT, the output file that will be created at the target node, in the default directory for the user named BEANS.
5. The read loop in this procedure reads a message from the logical link, edits the data, and places the record in the output file.

Example 14-2 A PL/I Target Task

TARGET_TASK: PROCEDURE; /* (1) */ DECLARE (INFILE,OUTFILE) FILE; /* Files */ DECLARE 1 LOG_MESSAGE, /* Structure to read in messages */ 2 STATUS FIXED BIN(31), 2 TEXT CHARACTER(40) VARYING; DECLARE MESSAGE CHARACTER(80); /* Variable to convert message */ PUT STRING(MESSAGE) EDIT(' ') (A(80)); ON UNDEFINEDFILE(INFILE) GOTO FILE_ERROR; /* Network errors */ /* (2) */ ON ENDFILE(INFILE) GOTO FINISH; /* Normal completion */ /* (3) */ OPEN FILE (INFILE) RECORD SEQUENTIAL INPUT TITLE ('SYS$NET'); /* Open SYS$NET */ /* (4) */ OPEN FILE(OUTFILE) RECORD SEQUENTIAL OUTPUT TITLE('TASK.DAT'); /* Open output log file */ LOOP: /* (5) */ READ FILE(INFILE) INTO (LOG_MESSAGE); PUT STRING(MESSAGE) EDIT(STATUS,TEXT) (F(6),X,A); WRITE FILE(OUTFILE) FROM (MESSAGE); GOTO LOOP; FINISH: CLOSE FILE(INFILE); CLOSE FILE(OUTFILE); RETURN; FILE_ERROR: PUT SKIP LIST('Input file error',ONCODE()); RETURN; END;

This chapter describes the following topics:

• Program sections, which are groupings of data made by the compiler and used by the linker
• The addressability of variables

Refer to the Kednos PL/I for OpenVMS Systems Reference Manual for information on storage classes.

15.1 Program Sections

When the PL/I compiler creates an object module, it groups data in the object module into contiguous areas called program sections. The data is grouped according to its attributes-for example, whether it contains executable code or read/write variables.

The compiler also writes, into each object module, information about the program sections contained in it. The linker uses this information when it binds object modules into an executable image. As the linker allocates virtual memory for the image, it groups program sections that have similar attributes.

15.1.1 Attributes of Program Sections

Table 15-1 lists the attributes that can be applied to program sections.

Table 15-1 Program Section Attributes

Attribute1	Meaning
PIC or NOPIC	The program section or data it refers to does not depend on any specific virtual memory location (PIC), or the program section depends on one or more virtual memory locations (NOPIC).
CON or OVR	The program section will be concatenated with other program sections with the same name (CON), or will be overlaid on the same memory locations (OVR).
REL or ABS	The data in the program section must be relocated to a virtual memory address (REL), or does not occupy virtual memory (ABS).
GBL or LCL	The program section contains definitions for symbols that are shared with other program sections or modules (GBL), or are local to the current program section (LCL).
EXE or NOEXE	The program section contains executable code (EXE), or does not contain executable code (NOEXE).
WRT or NOWRT	The program section contains data that can be modified (WRT), or data that cannot be modified (NOWRT).
RD or NORD	These attributes are not currently used.
SHR or NOSHR	The program section can be shared in memory (SHR), or cannot be shared in memory (NOSHR).

Kednos PL/I for OpenVMS VAX creates the following program sections for every program:

• $CODE-contains all executable code and constant data.
• $DATA-contains all internal static variables.

PL/I also creates additional program sections for external variables and global symbols. Table 15-2 summarizes the program sections that PL/I creates for variables declared with different storage class attributes.

Table 15-2 Program Sections for VAX PL/I Variables

Storage Class Attributes	Program Section Name1	Program Section Attributes
EXTERNAL CONTROLLED	name	PIC, OVR, REL, GBL, NOSHR, NOEXE, RD, WRT
EXTERNAL STATIC 2	name	PIC, OVR, REL, GBL, SHR, NOEXE, RD, WRT
EXTERNAL READONLY	name	PIC, OVR, REL, GBL, SHR, NOEXE, RD, NOWRT
INTERNAL STATIC	$DATA	PIC, CON, REL, LCL, NOSHR, NOEXE, RD, WRT
INTERNAL READONLY	$CODE	PIC, CON, REL, LCL, SHR, EXE, RD, NOWRT
GLOBALDEF	$DATA	PIC, CON, REL, LCL, NOSHR, NOEXE, RD, WRT
GLOBALDEF (psect-name)	psect-name	PIC, CON, REL, GBL, SHR, NOEXE, RD, WRT
GLOBALDEF READONLY	$CODE	PIC, CON, REL, LCL, SHR, EXE, RD, NOWRT
GLOBALDEF READONLY	psect-name	PIC, CON, REL, GBL, SHR, NOEXE, RD, NOWRT

PL/I creates the following program sections for every program:

• $CODE$-contains all executable code and constant data.
• $LINK$-contains all linkage data subject to link-time address fixups.

PL/I also creates additional program sections for external variables and global symbols. Table 15-3 summarizes the program sections that PL/I creates for variables declared with different storage class attributes.

Table 15-3 Program Sections for Alpha PL/I Variables

Storage Class Attributes	Program Section Name1	Program Section Attributes
EXTERNAL CONTROLLED	name	NOPIC, OVR, REL, GBL, NOSHR, NOEXE, WRT, NOMOD
EXTERNAL	name	NOPIC, OVR, REL, GBL, NOSHR, NOEXE, WRT, NOMOD
GLOBALDEF FILE	$DATA$	NOPIC, CON, REL, LCL, NOSHR, NOEXE, WRT, MOD
FILE	name	NOPIC, OVR, REL, GBL, NOSHR, NOEXE, WRT, MOD
EXTERNAL READONLY	name	NOPIC, OVR, REL, GBL, NOSHR, NOEXE, NOWRT, NOMOD
CONDITION	name	NOPIC, OVR, REL, GBL, NOSHR, NOEXE, NOWRT, NOMOD
STATIC or GLOBALDEF	$BSS$	NOPIC, CON, REL, LCL, NOSHR, NOEXE, WRT, NOMOD
INITIAL or GLOBALDEF INITIAL	$DATA$	NOPIC, CON, REL, LCL, NOSHR, NOEXE, WRT, NOMOD
READONLY or GLOBALDEF READONLY	$LITERAL$	PIC, CON, REL, LCL, SHR, NOEXE, NOWRT, MOD
GLOBALDEF (psect-name)	psect-name	NOPIC, CON, REL, GBL, NOSHR, NOEXE, WRT, NOMOD
GLOBALDEF (psect-name) READONLY	psect-name	NOPIC, CON, REL, GBL, NOSHR, NOEXE, NOWRT, NOMOD
FORMAT	$DPLI_FMTCONST$	NOPIC, CON, REL, LCL, NOSHR, NOEXE, NOWRT, MOD

In a FORTRAN program, separately compiled procedures share data by declaring common sections and specifying the names of one or more variables to be placed in those sections. Each named common section represents a separate program section; each procedure that declares the common section with the same name can access the same variable.

A PL/I external variable called XYZ therefore corresponds to a FORTRAN common section called XYZ. The following examples illustrate PL/I procedures and FORTRAN procedures that share data.

STRING.PLI

STRING: PROCEDURE OPTIONS(MAIN); DECLARE XYZ EXTERNAL CHARACTER(20), PRSTRING ENTRY; XYZ = 'THIS IS A STRING'; CALL PRSTRING; END;

PRSTRING.FOR

SUBROUTINE PRSTRING CHARACTER*20 STRING COMMON /XYZ/ STRING WRITE (6,20) STRING 20 FORMAT (' ',A20) RETURN END

In this example, the PL/I external variable XYZ corresponds to the FORTRAN common section named XYZ. The FORTRAN procedure displays the data in the common section.

To share more than one variable in a program section with a FORTRAN program, the PL/I variables must be declared within a structure. For example:

NUMBERS.PLI

NUMBERS: PROCEDURE; DECLARE 1 NUMBERS EXTERNAL, 2 FIRST FIXED(31), 2 SECOND FIXED(31), 2 THIRD FIXED(31), FNUM ENTRY; FIRST = 1; SECOND = 2; THIRD = 3; CALL FNUM; END;

FNUM.FOR

SUBROUTINE FNUM INTEGER*4 INUM,JNUM,KNUM COMMON /NUMBERS/ INUM,JNUM,KNUM WRITE (6,10) (INUM,JNUM,KNUM) 10 FORMAT (3I8) RETURN END

In this example, the fixed binary variables declared in the PL/I external structure NUMBERS correspond to the FORTRAN INTEGER*4 variables in the common section of the same name. Note that in a FORTRAN common section, all variables must be either integers or character strings. Variables of different data types cannot be grouped into the same common section.