PAM Programming Manual Abstract This manual describes the programmatic interfaces to Ethernet and token-ring LANs provided by the Port Access Method (PAM) subsystem for applications running on Himalaya S-series servers. This manual is intended for application programmers. Product Version Port Access Method G06 Supported Releases This manual supports G06.01 and all subsequent G-series releases until otherwise indicated in a new edition.
Document History Part Number Product Version Published 137676 Port Access Method G05 February 1998 142482 Port Access Method G07 August 1998 Ordering Information For manual ordering information: domestic U.S. customers, call 1-800-243-6886; international customers, contact your local sales representative. Document Disclaimer Information contained in a manual is subject to change without notice.
PAM Programming Manual Glossary Index Figures Tables What’s New in This Manual v Manual Information v New and Changed Information v About This Manual vii Who Should Use This Manual What’s in This Manual Other Manuals vii vii vii Your Comments Invited viii Notation Conventions viii Abbreviations x 1. Introduction Overview of Features and Architecture 1-1 The PAM Subsystem’s Role Within the System 1-1 2.
3. Link-Level Interfaces (continued) Contents 3.
B. Link-Level Programming Examples (continued) Contents B.
Tables Contents Tables Table 1. Summary of Contents vii Table A-1. Debug Errors Table A-2. Transitory Error Table A-3.
What’s New in This Manual Manual Information PAM Programming Manual Abstract This manual describes the programmatic interfaces to Ethernet and token-ring LANs provided by the Port Access Method (PAM) subsystem for applications running on Himalaya S-series servers. This manual is intended for application programmers. Product Version Port Access Method G06 Supported Releases This manual supports G06.01 and all subsequent G-series releases until otherwise indicated in a new edition.
Editorial Changes What’s New in This Manual • The Introduction has been rewritten to clarify terms.
About This Manual This manual describes the programmatic interface to the Port Access Method (PAM) subsystem running on Himalaya S-series servers. The PAM subsystem provides backward compatibility for applications that used the port interfaces provided on Himalaya K-series systems by the Tandem LAN Access Method (TLAM). This manual describes how to write applications that use the file-system and messagesystem interfaces.
Your Comments Invited About This Manual • Token Ring ServerNet Adapter Hardware Installation Guide Your Comments Invited After using this manual, please take a moment to send us your comments. You can do this by returning a Reader Comment Card or by sending an Internet mail message. A Reader Comment Card is located at the back of printed manuals and as a separate file on the Tandem User Documentation disc. You can either fax or mail the card to us.
General Syntax Notation About This Manual { } Braces. A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list may be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: LISTOPENS PROCESS { $appl-mgr-name } { $process-name } ALLOWSU { ON | OFF } | Vertical Line.
Notation for Management Programming Interfaces About This Manual Notation for Management Programming Interfaces The following list summarizes the notation conventions used in the boxed descriptions of programmatic commands, event messages, and error lists in this manual. UPPERCASE LETTERS. Uppercase letters indicate names from definition files; enter these names exactly as shown. For example: ZCOM-TKN-SUBJ-SERV lowercase letters.
Abbreviations About This Manual TLAM. Tandem LAN Access Method TRSA.
Abbreviations About This Manual PAM Programming Manual— 142482 xii
1 Introduction This section provides an overview of PAM and a description of the facilities for managing PAM. Overview of Features and Architecture PAM provides a set of standard programmatic interfaces that allows you to write applications without regard to the underlying physical local area network (LAN). These standard interfaces eliminate the need for separate sets of code for specific LAN types. The PAM subsystem provides access to token-ring or Ethernet LANs on a Himalaya S-series system.
The PAM Subsystem’s Role Within the System Introduction Figure 1-1. PAM Components Processor Management Interface Application Interface SCF Message System Interface File-System Interface PAM Clients PAM Applications SNAX over Token Ring LLC2 Applications PAM Mgr QIO Shared Memory Segment PAM LIF LIF SLSA MFIOB FESA E4SA LIF TRSA CDT 001.
The PAM Subsystem’s Role Within the System Introduction • • • FESA (Fast Ethernet ServerNet Adapter) on page 1-5 E4SA (Ethernet 4 ServerNet Adapter) on page 1-5 TRSA (Token-Ring ServerNet Adapter) on page 1-5 PAM Clients PAM clients are subsystems or user applications that access the port interface or the LLC2 interface by using file-system or message-system calls. Examples of applications include AppleTalk and Open System Interconnection (OSI) subsystems and customer applications.
The PAM Subsystem’s Role Within the System Introduction PAM Process The PAM process provides the interface to the SLSA subsystem for Ethernet, LLC1 and LLC2 applications, SNAX/XF and SNAX/APN, and EMS. EMS makes event messages generated by the PAM process available to management applications. EMS collects, logs, and distributes event messages that provide information to help you monitor the network environment, analyze failures, and recognize and handle critical problems.
The PAM Subsystem’s Role Within the System Introduction PAM Manager (PAMMAN) Process The PAMMAN process, $ZZPAM, is a process pair that provides the interface between the PAM subsystem and the Subsystem Control Point (SCP) process. The SCP process is required for management of the PAM subsystem. The SCP process is used by the SCF interactive interface as well as by management applications.
The PAM Subsystem’s Role Within the System Introduction Figure 1-3. PAM SCF Object Hierarchy PROCESS LINE PORT ETHERNET LLC1 LLC2 MSAP SNATR SESSION CDT 006.CDD PROCESS Object The PAM PROCESS object determines whether a PAM process is running in the system. The PAM PROCESS object provides the interface to the ServerNet LAN Systems Access (SLSA) subsystem for Ethernet and token ring. The PAM process also generates Event Management Service (EMS) messages.
Introduction The PAM Subsystem’s Role Within the System similar to how an application interacts with files; the application can open PORTs, perform reads and writes to exchange data with a remote LAN entity, then close them. The PORT object provides the following types of LSAPs: Ethernet The Ethernet PORT allows direct access to the DIX-compatible Ethernet interface (using a protocol type field instead of a length field as in IEEE 802.3).
The PAM Subsystem’s Role Within the System Introduction Figure 1-4. PAM Programmatic Interfaces Use the File System Interface LLC2 appl. Ethernet appl. SNAX/TR appl. LLC1 appl. PORT Object Uses the Message System Interface LLC1 Ethernet LLC2 Port Interface PORT Object SESSION Object PAM TRSA E4SA or FESA MSAP Object TRSA CDT 004.CDD SESSION Object The SESSION object defines the link station for LLC2-type connections and a SNAX session over a token-ring LAN.
2 File-System Procedures Standard file-system procedure calls are used by application processes running in a Himalaya S-series server to interact with the Port Access Method (PAM) using the PORT (LLC1 or Ethernet) interfaces. The PORT interface provides link-level access to the LAN connected to the server.
Using the PORT Interface File-System Procedures SETMODENOWAIT is identical to SETMODE except that the procedure call itself is performed as a nowait operation (that is, the SETMODENOWAIT call must be completed by a subsequent AWAITIO call). AWAITIO waits for completion of an outstanding nowait I/O operation FILE_GETINFO_ obtains error information pertaining to the most recently completed file-system procedure call.
3 Link-Level Interfaces This section describes link-level programmatic interfaces that provide level-2 services through link-level service access points (LSAPs). These LSAPs are part of the Port Access Method (PAM) process.
File-System Procedure Calls Link-Level Interfaces File-System Procedure Calls The level-2 programmatic interfaces use file-system procedure calls to communicate with ports. Applications format buffers containing multiple service data units (SDUs)— referred to as aggregate SDU messages (Aggr^SDUs)—and send them to a port. SDUs are units of information passed between an application and an LSAP supported by PAM.
Port Type Identifiers (Ethernet Only) Link-Level Interfaces • An exchange identification (XID) or Test PDU is received that is destined for the LLC1 port’s protocol type. • SETMODE sets a port’s data forward count (DFC) and data forward time (DFT) parameters. SETMODEs are queued with WRITEs on the WRITE queue. PAM supports the following SETMODE functions: • • • • #18 (SM^THRESHOLD) sets the current values for the DFC and DFT parameters to user specified values.
Port Type Identifiers (Ethernet and Token Ring) Link-Level Interfaces Port Type Identifiers (Ethernet and Token Ring) The ZPAM^Val^Port^Type identifier is a required input parameter for all primitives in the L2S Formatting Library. It is used to determine how the fields of the SDUs are to be formatted and interpreted. The two valid port type identifiers defined for level-2 services (L2S) is ZPAM^Val^Port^Type^LLC2 (IEEE 802.2 Link Level Control, Type 2). The IEEE 802.
Delivery Mode Link-Level Interfaces applications for LLC1 and Ethernet type ports. LLC2 type frames received from tokenring adapters are aggregated and forwarded to the host. Ports can be stopped, started, or aborted independently of other objects in PAM. All port attributes can be altered in the stopped state; however, only the DFT and DFC parameters can be altered while a port is in the started state by using a SETMODE filesystem call.
Formatting Library for Ethernet Link-Level Interfaces Formatting Library for Ethernet The Formatting Library provides the header files to include in your application and the object files to which you will link or bind. This subsection describes the use of primitives (function calls or procedures) in the L2S Formatting Library for Ethernet.
Formatting an Aggregate SDU Header (Ethernet) Link-Level Interfaces primitive initializes an aggregate SDU buffer, formats the aggregate SDU header, and formats an initial individual SDU header. Subsequent SDU headers formatted with the ZL2S^Frmt^SDU^Hdr^ primitive must be passed only aggregate SDU buffers that have already been initialized by one of the two preceding primitives; otherwise unpredictable results can occur.
Formatting an Aggregate SDU and an SDU Header (Ethernet) Link-Level Interfaces The fields of the aggregate SDU header are defined as follows: zWork This field is reserved for internal use. zVsn This field contains the version number of the aggregate SDU header. It is automatically inserted by the L2S Formatting Library primitives. The version number determines the format of the aggregate SDUs. zAddr All traffic through the port is associated with the value specified here.
Formatting an Aggregate SDU and an SDU Header (Ethernet) Link-Level Interfaces The aggregate SDU header begins at the first word of the aggregate SDU buffer, followed directly by the initial SDU header. This primitive passes back to the application an offset, in bytes, from the beginning of the aggregate SDU buffer to the location where the user data begins.
Formatting an Aggregate SDU and an SDU Header (Ethernet) Link-Level Interfaces The Ethernet Port^Type supports only the UI SDUType. The LLC1 Port^Type supports all three SDUTypes. For C programs replace the caret (^) with an underscore ( _ ). P^F^Flag (INT) Optional input that allows applications to set or reset the poll/final bit. The poll (P) bit is used in command PDUs to solicit a response from the addressed peer.
Formatting an SDU Header (Ethernet) Link-Level Interfaces Formatting an SDU Header (Ethernet) This primitive formats an individual SDU header within a previously created aggregate SDU buffer. The SDU header begins at the first word boundary after the aggregate SDU header, or the first word boundary after the preceding SDU, if any. This primitive passes back to the application a byte offset from the beginning of the aggregate SDU buffer indicating where the user data, if any, begins.
Formatting an SDU Header (Ethernet) Link-Level Interfaces Rsp^Flag (INT) An optional input that designates whether this PDU is a command (false) or a response (true). The default value is false (command). P^F^Flag (INT) Optional input that allows applications to set or reset the Poll (P) bit in command PDUs to solicit a response from the addressed peer or the Final (F) bit in response PDUs to indicate a response to a solicitation (poll). The default value is false (not set). Foreign^Addr^ptr (STRING .
Formatting an SDU Header (Ethernet) Link-Level Interfaces LLC1 SDU Header Format The LLC1 SDU header formatted by this L2S primitive is defined as follows: def 02 02 02 02 02 02 02 ZL2S-DDL-LLC-SDU-Hdr. zSDU-Size type ZSPI-DDL-INT. zForeign-SAP type ZL2S-DDL-LLC-ADDR. zCtl type ZSPI-DDL-BYTE. zP-F-Flag type ZSPI-DDL-BYTE. zRsp-Flag type ZSPI-DDL-BYTE. zPri type ZSPI-DDL-BYTE. zFiller type ZSPI-DDL-BYTE. occurs 19 times. end. def ZL2S-DDL-LLC-Addr 02 zLSAP type ZSPI-DDL-INT.
Getting an SDU (Ethernet) Link-Level Interfaces zPri PAM does not use the field. zFiller This is a 19-byte pad to fill out the 32-byte PDU header. Ethernet SDU Header Format The Ethernet SDU header formatted by this L2S primitive is defined as follows: def ZL2S-DDL-Enet-SDU-Hdr. 02 zSDU-Size type ZSPI-DDL-INT. 02 zEnet-Hdr type ZL2S-DDL-ENET-HDR. end. def ZL2S-DDL-Enet-Hdr. 02 zDest-MAC-Addr type ZSPI-DDL-BYTE. occurs 6 times. 02 zSrc-MAC-Addr type ZSPI-DDL-BYTE. occurs 6 times.
Getting an SDU (Ethernet) Link-Level Interfaces The syntax for this primitive is INT PROC ZL2S^Get^SDU^ ( Aggr^SDU^Buff^ptr, ,L2S^Type ,L2S^SDU^Type ,P^F^Flag ,Rsp^Flag ,Foreign^Addr^Offset^B ,User^Data^Offset^B ,User^Data^Size^B ,Service^Class ) EXTENSIBLE; The parameters for this primitive are defined as follows: Aggr^SDU^Buff^ptr (STRING .EXT) Required input used to reference the buffer used for the inbound aggregate SDU.
Error Codes (Ethernet) Link-Level Interfaces Foreign^Addr^Offset^B (INT .EXT) Optional output used to indicate where the peer’s foreign address can be found. It is in the form of an offset, in bytes, from the beginning of the aggregate SDU buffer. User^Data^Offset^B (INT .EXT) Optional output that returns the offset, in bytes, from the beginning of the inbound aggregate SDU buffer to the location where the user data, if any, begins.
Error Codes (Ethernet) Link-Level Interfaces ZL2S^Err^Frmt^Incomp^Params ZL2S^Frmt^SDU^Hdr^ or ZL2S^Frmt^Aggr^SDU^n^SDU^Hdr^ was called with an SDUType that is not supported for the Port^Type indicated. Correct the invalid type specification and repeat the primitive. ZL2S^Err^Frmt^No^More^Room ZL2S^Frmt^SDU^Hdr^ was called to format an SDU within an aggregate SDU buffer that did not have sufficient space remaining to hold the SDU header and the associated user data.
Additional Library Headers for Ethernet Link-Level Interfaces Additional Library Headers for Ethernet PAM supports two SDU headers for Ethernet applications that cannot be formatted using the primitives from the formatting library. These headers send LLC2 frames over LLC1 ports enabled for LLC2 (for example, LLC2ENABLED set using the SCF ADD PORT command). Header for LLC1 MAC Frames The Ethernet SDU header format for LLC1 MAC frames is defined as follows def ZL2S-DDL-LLC1-SDU-Hdr.
Header for LLC2 MAC Frames Link-Level Interfaces zSDU-data The first byte of data in the frame. Header for LLC2 MAC Frames The Ethernet SDU header format for LLC2 MAC frames is defined as follows: def ZL2S-DDL-LLC2-SDU-Hdr. 02 zSDU-Size type ZSPI-DDL-INT. 02 zDest-Mac-addr type ZSPI-DDL-BYTE occurs 6 times. 02 zSrc-MAC-addr type ZSPI-DDL-BYTE occurs 6 times. 02 zLength type ZSPI-DDL-INT. 02 zDSAP type zSPI-DDL-BYTE. 02 zSSAP type ZSPI-DDL-BYTE. 02 zCtrl1 type ZSPI-DDL-BYTE. 02 zCtrl2 type ZSPI-DDL-BYTE.
Header for LLC2 MAC Frames Link-Level Interfaces zCtrl2 For numbered frames, this is the second byte of the two-byte LLC Control field. For unnumbered frames, the data starts from this field.
Formatting Library for Token Ring Ports Link-Level Interfaces Formatting Library for Token Ring Ports This subsection describes the use of primitives in the L2TR Formatting Library for token ring ports.
Formatting an Aggregate SDU Header (Token Ring) Link-Level Interfaces ZL2TR^Frmt^SDU^Hdr^ primitive must be passed only aggregate SDU buffers that have already been initialized by one of the two preceding primitives; otherwise unpredictable results occur. Formatting an Aggregate SDU Header (Token Ring) Aggregate SDUs are created when the application determines that it needs to send one or more SDUs to an LSAP and there is no aggregate SDU waiting to be sent.
Formatting an Aggregate SDU and an SDU Header (Token Ring) Link-Level Interfaces Aggregate SDU Header Format The aggregate SDU header formatted by this L2TR primitive is defined as follows: def ZL2TR-DDL-Aggr-SDU-Hdr. 02 zWork type ZSPI-DDL-INT. occurs 2 times. 02 zVsn type ZSPI-DDL-INT. 02 zSDU-Type type ZSPI-DDL-INT. 02 zSAP-Value type ZSPI-DDL-BYTE. 02 zSDU-Cnt type ZSPI-DDL-INT. end. The fields of the aggregate SDU header are defined as follows: zWork This field is reserved for internal use.
Formatting an Aggregate SDU and an SDU Header (Token Ring) Link-Level Interfaces The LLC1 SDU header formatted by this L2TR primitive is described in the ZL2TR^Frmt^SDU^Hdr^ primitive that follows. The aggregate SDU header begins at the first word of the aggregate SDU buffer, followed directly by the initial SDU header. This primitive passes back to the application an offset, in bytes, from the beginning of the aggregate SDU buffer to the location where the user data begins. Note.
Formatting an SDU Header (Token Ring) Link-Level Interfaces The SDU type ZLATR^VAL^SDUTYPE^LLC2 is not supported for file-system applications. The results are unpredictable if a file-system application attempts to use LLC2 aggregate types. SDU^User^Data^Offset^B (INT .EXT) Conditional output returns the byte offset from the beginning of the aggregate SDU buffer where the application should begin placing data associated with an outbound SDU.
Formatting an SDU Header (Token Ring) Link-Level Interfaces mac^frame (STRING .EXT) For LLC1 frames, this required input points to an array of bytes that are formatted by mac^frame structure. mux^id (INT(32)) For LLC2 type aggregates, this input indicates the mux^id of the session. The results are unpredictable if a file-system application sends these SDU types. The SDU type ZLATR^VAL^SDUTYPE^LLC2 is not supported for file-system applications.
Formatting an SDU Header (Token Ring) Link-Level Interfaces LLC1 SDU Header Format The LLC1 SDU header formatted by this L2TR primitive is defined as follows: def ZL2TR-DDL-LLC1-SDU-Hdr. 02 zSDU-Size type ZSPI-DDL-INT. end. def ZL2TR-DDL-LLC1-mac-frame. 02 ac type ZSPI-DDL-BYTE. 02 fc type ZSPI-DDL-BYTE. 02 Dest-MAC type ZSPI-DDL-BYTE occurs 6 times. 02 Src-MAC type ZSPI-DDLBYTE occurs 6 times. 02 Route type ZSPI-DDL-BYTE occurs 18 times. 02 DSAP type ZSPI-DDL-BYTE. 02 SSAP type ZSPI-DDL-BYTE.
Getting an SDU (Token Ring) Link-Level Interfaces SSAP The source service access point (SSAP) address: LLC-Ctrl LLC control field. SDU-data User data. For detailed information on these fields, refer to the IEEE 802.5 protocol specifications. Getting an SDU (Token Ring) This primitive is used to find and interpret the first (or next) SDU in an inbound aggregate SDU buffer.
Error Codes (Token Ring) Link-Level Interfaces User^Data^Size^B (INT(32) .EXT) Optional output that returns the size, in bytes, of the user data associated with the SDU, if any. If there is no user data, a value of zero is returned.
Additional Header for Token Ring Link-Level Interfaces Additional Header for Token Ring PAM supports an SDU header that cannot be formatted using the primitives from the formatting library. This header is used to send LLC2 frames over token ring on LLC1 ports. The format for this SDU header is as follows: def zL2TR-DDL-8025-SDU. 02 z8025-SDU-Hdr type ZL2TR-DDL-8025-SDU-HDR. 02 z8025-MAC-Frame type ZL2TR-DDL-8025-MAC-FRAME. end. def zL2TR-DDL-8025-SDU-Hdr. 02 zSDU-Size type ZSPI-DDL-INT. end.
Additional Header for Token Ring Link-Level Interfaces AC Access control. FC Function control. zDest-MAC The destination MAC address. zSrc-MAC The source MAC address. If the most significant bit of byte 0 is 1, then routing information is present in the inbound SDU. Route Routing information zDSAP The destination service access point (DSAP) address: zSSAP The source service access point (SSAP) address: LLC-Unnum The LLC control field for unnumbered LLC frames.
Additional Header for Token Ring Link-Level Interfaces PAM Programming Manual— 142482 3- 32
A File-System Error Codes This appendix lists all file-system errors applicable to PAM. File-system error codes fall into three general categories: • • • Debug errors indicate that you must change something in your program, recompile, and restart. These are listed in Table A-1 Transitory errors indicate a temporary problem. Your program should wait a while and then reissue the particular procedure call.
File-System Error Codes Table A-3. Fatal Errors Code Error Description 33 I/O process unable to obtain I/O segment space. 53 File system internal error. 60 Device downed or not open, or process has failed since it opened file. 66 Device is down. 157 I/O process internal error. 193 Invalid or missing microcode file. 200 Device is owned by the other port. 210 Ownership changed during operation. 230 CPU power failed, then restored. 231 Controller power failed, then restored.
B Link-Level Programming Examples This appendix presents annotated programming examples coded in TAL, C, and Pascal. Sample TAL Calling Sequences The discussions that follow present TAL coding examples illustrating the major functional parts of a link-level application. In this sample exercise, the test program communicates with a node in an attached LAN by way of a PORT. Once the PORT has been OPENed, the application program communicates with the link-level interface by sending and receiving SDUs.
Data Declarations Link-Level Programming Examples Data Declarations The coding example assumes the presence of the following data declarations: --/---------------------------------------------------------------/ -L2 Service Access Point Exercise Program: Declarations --/---------------------------------------------------------------/ -L2SAP File Information --/---------------------------------------------------------------/ INT .INT^L2SAP^file^name^ptr [0:11] := [ 12 * [” STRING .
Procedures Link-Level Programming Examples Procedures The application program must define the following procedures: --/---------------------------------------------------------------/ --/ Procedures --/---------------------------------------------------------------/ INT(32) PROC SUBTRACTTRIPLE( A, B ); INT .A, .
Procedures Link-Level Programming Examples report^buf^ptr ’:=’ [”Send Failed”]; ?ENDIF 1 ?IF 2 report^buf^ptr ’:=’ [”Receive Failed”]; ?ENDIF 2 CALL Write ( report^file^num, report^buf^ptr, 14 ); CALL AbEnd; END; --/---------------------------------------------------------------/ -Service Access Point Exercise Program: Procedures --/---------------------------------------------------------------/ -PROC: Initialize --/---------------------------------------------------------------/ PROC BEGIN INT INT INT S
Procedures Link-Level Programming Examples @startup^message^ptr := end^addr + 1; SCAN startup^message^ptr WHILE " " -> @startup^message^ptr; end^addr := NumIn ( startup^message^ptr, Port^type, 10, error ); IF error THEN BEGIN CALL Clear^Report^Buffer; report^buf^ptr ':=' ["Port type is bad"]; CALL Write^Report^Buf^and^AbEnd; END; --/---------------------------------------------------------------/ -Look for Command Code ( ZLAM^Val^SDU^Type^...
Procedures Link-Level Programming Examples ( loop^cnt = 0 ) THEN BEGIN CALL Clear^Report^Buffer; report^buf^ptr ':=' ["Loop count is bad"]; CALL Write^Report^Buf^and^AbEnd; END; --/---------------------------------------------------------------/ -Look for SDU count.
Procedures Link-Level Programming Examples ( NoWait^depth > Max^NoWait^Depth ) THEN BEGIN CALL Clear^Report^Buffer; report^buf^ptr ’:=’ [”NoWait depth is bad.”]; CALL Write^Report^Buf^and^Abend; END; --/---------------------------------------------------------------/ -Pick up Foreign Address. It is a string of ASCII digits. -Convert it into a string of hex digits.
Finding a Free Buffer Link-Level Programming Examples Finding a Free Buffer The application must provide a function that allows it to find a free buffer to contain the aggregate SDU. --/---------------------------------------------------------------/ -FUNCTION: Find Free Buffer --/---------------------------------------------------------------/ INT PROC Find^Free^Buffer ( buffer^lst^ndx ); INT(32) .
Sending the Aggregate SDU Link-Level Programming Examples current^user^data^size^B ) ) <> ZL2S^Err^Frmt^Ok ) THEN BEGIN CALL Clear^Report^Buffer; report^buf^ptr ’:=’ [”SDU Hdr Error: “]; CALL NumOut ( report^buf^ptr[18], frmt^error, 10, 2 ); CALL Write^Report^Buf^and^AbEnd; END; IF current^user^data^size^B THEN Aggr^SDU^buf^ptr[data^offset^B] ’:=’ test^char FOR 1 BYTES & Aggr^SDU^buf^ptr[data^offset^B] FOR ( current^user^data^size^B - 1 ) BYTES; END; RETURN ( data^offset^b + current^user^data^size^B ); EN
Receiving an Aggregate SDU Link-Level Programming Examples Receiving an Aggregate SDU The application must also provide a procedure for receiving aggregate SDUs from a PORT. --/---------------------------------------------------------------/ -PROC: Receive^ --/---------------------------------------------------------------/ PROC Receive^ ( buffer^lst^ndx ); INT(32) buffer^lst^ndx; BEGIN INT STRING file^error; .EXT Aggr^SDU^buf^ptr; @Aggr^SDU^buf^ptr := @buffer^lst^ptr[buffer^lst^ndx].
Testing the L2S Interface Link-Level Programming Examples [”SetMode failed - Error: “]; CALL NumOut ( report^buf^ptr[21], file^error, 10, 4 ); CALL Write^Report^Buf^and^AbEnd; END; END; --/---------------- End of Open_ procedure -----------------------/ --/---------------------------------------------------------------/ -PROC: Close^ --/---------------------------------------------------------------/ PROC Close^; BEGIN INT file^error; CALL Close ( L2SAP^file^num ); IF <> THEN BEGIN CALL FileInfo ( L2SAP
Testing the L2S Interface Link-Level Programming Examples WHILE Find^Free^Buffer ( buffer^lst^ndx ) AND ( current^user^data^size^b <= end^user^data^size^b ) DO BEGIN test^char := $UDbl ( current^user^data^size^b ) ’\’ 256; ?IF 1 CALL Send^ ( buffer^lst^ndx ); ?ENDIF 1 ?IF 2 CALL Receive^ ( buffer^lst^ndx ); ?ENDIF 2 current^user^data^size^b := current^user^data^size^b + 1; pending^req^cnt := pending^req^cnt + 1; END; IF pending^req^cnt THEN BEGIN CALL AwaitIOX ( L2SAP^file^num, , , buffer^lst^ndx, 30000D
Sample C Calling Sequences Link-Level Programming Examples report^buf^ptr[46] ’:=’ [” Sec “]; CALL Write ( report^file^num, INT^report^buf^ptr, 60 ); END; Sample C Calling Sequences The following paragraphs present an L2S Access Point exercise using C coding examples that are functionally similar to the preceding TAL coding examples. In this sample exercise, the test program communicates with a node in an attached LAN by way of a PORT.
Procedures Link-Level Programming Examples Rsp_Flag, Loop_Cnt, SDU_Cnt, Begin_User_Data_Size_B, Current_User_Data_Size_B, End_User_Data_Size_B, NoWait_Depth; char Foreign_Addr[zlam_val_mac_addr_size_b] = {0,0,0,0,0,0}; /* -------------------------- Other ---------------------------- */ int int int long int char Max_User_Data_Size_B = ( Max_Req_Size sizeof ( struct zl2s_ddl_aggr_sdu_hdr_def ) sizeof ( struct zl2s_ddl_enet_sdu_hdr_def ) ); pending_request_cnt = 0; Aggr_SDUs_left; buffer_lst_ndx; file_error
Procedures Link-Level Programming Examples else fprintf(stdout, “Command Code is bad\n”) exit(Abend_exit) } /* ----------------------- Get P/F flag ------------------------ */ if (argc >= 5 P_F_Flag = atoi (argv[4]); else { fprintf(stdout, “P F flag is bad\n”); exit(Abend_exit); }; /* ---------------------- Get response flag -------------------- */ if (argc >= 6) Rsp_Flag = atoi (argv[5]); else { fprintf(stdout, “Response flag is bad\n”); exit(Abend_exit); }; /* --------------------- Look for Loop Count -
Procedures Link-Level Programming Examples }; /* -------------------- Test Foreign Address ------------------- */ if (argc < 12) { fprintf(stdout, “Foreign Address is bad.\n”); exit(Abend_exit); } /* ------------------- Convert Foreign Address -------------------Convert a string of ASCII digits into a string of hex digits.
Finding a Free Buffer Link-Level Programming Examples Finding a Free Buffer The application must provide a function that allows it to find a free buffer to contain the aggregate SDU.
Sending the Aggregate SDU Link-Level Programming Examples Rsp_Flag, (char *)Foreign_Addr, (int * )&data_offset_b, Current_User_Data_Size_B ); if ( frmt_error != zl2s_err_frmt_ok ) { fprintf(stdout, “SDU Hdr Error:%d\n “, frmt_error); exit(Abend_exit); }; for (count = 1; count <= Current_User_Data_Size_B; count++) Aggr_SDU_buf [ data_offset_b + count ] = test_char; }; return ( data_offset_b + Current_User_Data_Size_B ); } Sending the Aggregate SDU The application must provide a procedure for sending an ag
Receiving an Aggregate SDU Link-Level Programming Examples Receiving an Aggregate SDU The application must also provide a procedure for receiving aggregate SDUs from a PORT. #pragma page “PROCEDURE: Receive_” /* ---------------------------------------------------------------PROCEDURE: Receive_ ---------------------------------------------------------------- */ void Receive_ ( buffer_lst_ndx ) long int buffer_lst_ndx; { int int file_error; cc; buffer_lst[ buffer_lst_ndx ].
Closing a PORT Link-Level Programming Examples FILEINFO ( L2SAP_file_num, (int *)&file_error ); fprintf(stdout, “SetMode failed - Error: %d\n”, file_error); exit(Abend_exit); }; } /* --------------------- End of Open_ procedure ---------------- */ Closing a PORT The application must also provide a procedure for closing PORTs.
Testing the L2S Interface Link-Level Programming Examples while (Find_Free_Buffer ( &buffer_lst_ndx ) && ( Current_User_Data_Size_B <= End_User_Data_Size_B )) test_char = ( Current_User_Data_Size_B % 256 ); { #if SEND Send_ ( buffer_lst_ndx ); #else Receive_ ( buffer_lst_ndx ); #endif Current_User_Data_Size_B = ( Current_User_Data_Size_B + 1 ); pending_request_cnt = ( pending_request_cnt + 1 ); }; if (pending_request_cnt) { cc = AWAITIOX ( (int *)&L2SAP_file_num,,, (long *)&buffer_lst_ndx, 30000L, ); if (
Sample Pascal Calling Sequences Link-Level Programming Examples Sample Pascal Calling Sequences The following paragraphs present an L2S Access Point exercise using Pascal coding examples that are functionally similar to the preceding TAL and C coding examples. In this sample exercise, the test program communicates with a node in an attached LAN by way of a PORT. Once the PORT has been OPENed, the application program communicates with the link-level interface by sending and receiving SDUs.
Data Definitions and Declarations Link-Level Programming Examples {-----------------------------------------------------------------Startup Message Parameters ------------------------------------------------------------------} Port_type, command_code, P_F_flag, rsp_flag, number_of_loops, SDU_cnt, begin_user_data_size_b, current_user_data_size_b, end_user_data_size_b, NoWait_depth : INTEGER; Foreign_Addr : FSTRING [( ZLAM_Val_MAC_Addr_Size_B + 2 )] {------------------------------ Other ------------------
Procedures Link-Level Programming Examples Procedures The application program must also define the following procedures: ?SECTION Procedures ?PAGE ’PROCEDURE: AbEnd_’ {-----------------------------------------------------------------PROCEDURE: AbEnd_ ------------------------------------------------------------------} PROCEDURE AbEnd_; BEGIN ?IF SEND WriteLn ( Output, ’Send Failed’:14 ); ?ELSE WriteLn ( Output, ’Receive Failed’:14, ’Curr.
Procedures Link-Level Programming Examples min_value : INTEGER; max_value : INTEGER ) : BOOLEAN; VAR error : INTEGER; start_addr : BYTEADDR; end_addr : BYTEADDR; BEGIN IF ( start_ndx > startup_msg_size_b ) THEN BEGIN Get_Int := False; RETURN; END; start_addr := BAddr ( startup_msg[ start_ndx ] ); end_addr := NumIn ( start_addr, result, base, error ); end_ndx := ( start_ndx + ( ReType ( end_addr, INTEGER ) - ReType ( start_addr, INTEGER ) ) ); Get_Int := ( error <> 0 ) OR ( result < min_value ) OR ( result
Procedures Link-Level Programming Examples {--------- Look for Port type ( ZLAM_Val_Port_Type_... ) ---------} IF Get_Int ( Scan_Blanks ( ( ndx + 1 ) ), ndx, 10, Port_Type, ZLAM_Val_Min_Port_Type, ZLAM_Val_Max_Port_Type ) THEN BEGIN WriteLn ( Output, ’Port type is bad’ ); AbEnd_; END; {-------- Look for Command Code ( ZLAM_Val_SDU_Type_...
Procedures Link-Level Programming Examples {-------------------------- Get P/F flag -------------------------} IF Get_Int ( Scan_Blanks ( ( ndx + 1 ) ), ndx, 10, P_F_flag, 0, 1 ) THEN BEGIN WriteLn ( Output, ’P F flag is bad’ ); AbEnd_; END; {---------------------- Get response flag ------------------------} IF Get_Int ( Scan_Blanks ( ( ndx + 1 ) ), ndx, 10, rsp_flag, 0, 1 ) THEN BEGIN WriteLn ( Output, ’Response flag is bad’ ); AbEnd_; END; {---------------------- Look for Loop Count --------------------
Procedures Link-Level Programming Examples {----------- Look for beginning user data size ( bytes ) ---------} IF Get_Int ( Scan_Blanks ( ( ndx + 1 ) ), ndx, 10, begin_user_data_size_B, 0, Max_User_Data_Size_B ) THEN BEGIN WriteLn ( Output, ’Begin User Data Size is bad.
Finding a Free Buffer Link-Level Programming Examples IF ( ( hex_digit_ndx MOD 2 ) = 0 ) THEN foreign_addr[ ( hex_digit_ndx DIV 2 ) + 1 ] := Chr ( ( hex_value * 16 ) OR Ord ( foreign_addr[ ( hex_digit_ndx DIV 2 ) + 1 ] ) ) ELSE foreign_addr[ ( hex_digit_ndx DIV 2 ) + 1 ] := Chr ( hex_value OR Ord ( foreign_addr[ ( hex_digit_ndx DIV 2 ) + 1 ] ) ); hex_digit_ndx := ( hex_digit_ndx + 1 ); END; {-------------------------- Initialize Buffers -------------------} FOR buffer_lst_ndx := 0 TO ( Max_NoWait_Depth -
Building an Aggregate SDU Link-Level Programming Examples Building an Aggregate SDU The application must provide a function for building the aggregate SDU.
Building an Aggregate SDU Link-Level Programming Examples Build_Aggr_SDU := ( data_offset_b + current_user_data_size_B ); END; (Sending the Aggregate SDU) SUBHEAD Sending the Aggregate SDU The application must provide a procedure for sending an aggregate SDU to a PORT.
Receiving an Aggregate SDU Link-Level Programming Examples Receiving an Aggregate SDU The application must provide a procedure for receiving aggregate SDUs from PORTs. ?PAGE ’PROCEDURE: Receive_’ {-----------------------------------------------------------------PROCEDURE: Receive_ ------------------------------------------------------------------} PROCEDURE Receive_ ( buffer_lst_ndx : LONGINT ); BEGIN buffer_lst[ buffer_lst_ndx ].in_use_flag := True; buffer_lst[ buffer_lst_ndx ].
Opening a PORT Link-Level Programming Examples Opening a PORT The application must also provide a procedure for opening PORTs.
Testing the L2S Interface Link-Level Programming Examples Testing the L2S Interface The following program tests all of the preceding code. The application program establishes a working connection between itself and the L2S interface by opening the PORT that connects the host system to the target LAN through TLAM.
Testing the L2S Interface Link-Level Programming Examples ?ENDIF buffer_lst[ buffer_lst_ndx ].in_use_flag := buffer_lst[ buffer_lst_ndx ].test_char := buffer_lst[ buffer_lst_ndx ].user_data_size_b := pending_request_cnt := ( pending_request_cnt - 1 Aggr_SDUs_left := ( Aggr_SDUs_left - 1 ); END UNTIL ( Aggr_SDUs_left <= 0 ); END; { FOR loop_cnt } False; 0; 0; ); end_time := JulianTimeStamp; Close_; ?IF SEND WriteLn ( Output, ’Send Complete ’ ); ?ELSE WriteLn ( Output, ’Receive Complete.
Testing the L2S Interface Link-Level Programming Examples PAM Programming Manual— 142482 B -36
Glossary This glossary defines the terms used in this manual and related terms. ABEND. (1) An abnormal end of a task or process. (2) An error condition that can result in the termination of a program. ABORT. A sensitive SCF command that terminates the operation of an object as quickly as possible; only enough processing is done to ensure subsystem security. ADD. A sensitive SCF command that adds an object to the PAM subsystem. aggregate SDU. A grouping of multiple SDUs into one request or response. ALTER.
(CSMA/CD) Glossary (CSMA/CD). A characteristic of network hardware that uses CSMA access combined with a mechanism that allows the hardware to detect when two stations simultaneously attempt transmission. Ethernet is an example of a well-known network based on CSMA/CD technology. DELETE. A sensitive SCF command that removes objects from the PAM subsystem. Only objects that were added with the ADD command can be deleted. DETAIL.
HELP Glossary HELP. An SCF command that displays information about commands and objects used to manage the PAM subsystem. Himalaya S-series servers. The set of servers in the Himalaya range of servers having product numbers beginning with the letter “S.” These servers run the Tandem NonStop Kernel operating system and implement the ServerNet architecture. INFO. A nonsensitive SCF command that displays the current or default attributes of the specified object. interactive input.
logical interface Glossary that is located in a small geographical area, whose communications technology provides a high-bandwidth, low-cost medium to which low-cost nodes can be connected. logical interface. The interface that allows an application or another process to communicate with data communications hardware. logical link control 1 (LLC1) ports. The ports that allow access to an LLC type 1 connectionless (IEEE 802.2) level 2 interface. logical link control 2 (LLC2) ports.
octal Glossary octal. A number system with 8-bit patterns represented by the symbols 0 through 7. Two octal digits represent one 6-bit character, the standard for data representation prior to the 8-bit byte, which is represented by hexadecimal notation. output destination. The destination to which the Subsystem Control Facility (SCF) directs output. The destination can be a disk file, an application process, a terminal, or a printer.
service data unit (SDU) Glossary service data unit (SDU). The information passed across the network to a peer entity and then up to the next layer. sensitive command. One that can be issued only by a user with a SUPER ID, by the owner of the subsystem, or by a member of the group of the owner of the subsystem. For Tandem communications subsystems, the sensitive commands can change the state or configuration of objects, start or stop tracing, or change the values of statistics counters.
Subsystem Control Facility Glossary Subsystem Control Facility. A subsystem used to issue configuration and information requests between the user and some communications subsystems. Subsystem Control Point. The management process for all Tandem data communications subsystems. SUPER ID. A user who can read, write, execute, and purge most files on the system. A super-group user is usually a member of a system-supervisor group. Members of the super group have group ID 255. timestamp.
$ZZLAN Glossary PAM Programming Manual— 142482 Glossary -8
Index A aggregate SDU header 3-2 aggregate SDU messages 3-2 AWAITIO See procedure calls C CANCELREQ See procedure calls Components, PAM 1-2 D data forward count 3-5 See DFC data forward time 3-5 See DFT DFC default value 3-5 DFT default value 3-5 DSM-related objects LINE object 3-1 PORT object 3-1 E EMS 1-4 F File-system interface 1-3 FILE_CLOSE_ See procedure calls FILE_GETINFOBYNAME_ See procedure calls FILE_GETINFO_ See procedure calls FILE_OPEN_ see procedure calls G Guardian file-system error cod
O Index MFIOB 1-5 MSAP object 1-8 Multifunction I/O board 1-5 O Object hierarchy 1-5 P PAM components of 1-5 PAM manager process 1-5 PAM objects LINE 1-6 MSAP 1-8 PROCESS 1-6 SESSION 1-8 PAMMAN 1-5 port closing 2-1 See also procedure calls,CLOSE_FILE_ reading from 2-1 See also procedure calls, READX writing to 2-1 See also procedure calls, WRITEX PORT interface procedure calls 2-2 See also procedure calls PORT object 3-1 attributes delivery mode 3-5 subtypes Ethernet 3-1 LLC1 1-7, 3-1 LLC2 1-7 Port obje
W Index SETMODE See procedure calls SETMODENOWAIT See procedure calls SLSA subsystem 1-3 SPI 1-3 Subsystem Programmatic Interface 1-3 W WINDOW interface operating parameters 2-2 WRITEX See procedure calls Z ZL2S-DDL-Aggr-SDU-Hdr data structure 3-8 zAddr field 3-8 zMAC_Addr field 3-8 zSDU_Cnt field 3-8 zVsn field 3-8 zWork field 3-8 ZL2S-DDL-Enet-Hdr data structure 3-14, 3-18, 3-19, 3-30 zDest_MAC_Addr field 3-14 zSrc_MAC_Addr field 3-14 ZL2S-DDL-Enet-SDU-Hdr data structure 3-14 zEnet_Hdr field 3-14 zSDU
Z Index ZL2S_Frmt_Aggr_SDU_n_SDU_Hdr_ primitive (continued) ZL2S_Val_SDUType_XID 3-10 L2S_Type 3-9 ZLAM_Val_Port_Type_Enet 3-9 ZLAM_Val_Port_Type_LLC1 3-9 P_F_Flag 3-10 Rsp_Flag 3-10 SDU_User_Data_Offset_B 3-10 SDU_User_Data_Size_B 3-10 ZL2S_Frmt_SDU_Hdr_ primitive 3-6, 3-11 Aggr_SDU_Buff_ptr 3-11 Foreign_Addr_ptr 3-12 L2S_SDU_Type 3-11 ZL2S_Val_SDUType_Test 3-11 ZL2S_Val_SDUType_UI 3-11 ZL2S_Val_SDUType_XID 3-11 L2S_Type 3-11 ZLAM_Val_Port_Type_Enet 3-11 ZLAM_Val_Port_Type_LLC1 3-11 P_F_Flag 3-12 Rsp_Fla
Z Index ZL2TR_Err_Frmt_No_More_Room 3-29 ZL2TR_Err_Frmt_No_More_SDUs 3-29 ZL2TR_Err_Frmt_Ok 3-29 ZL2TR_Frmt_Aggr_SDU_Hdr_ primitive 3-21 Aggr_SDU_Buff_Size_B field 3-23 sap_val field 3-23 sdu_type field 3-23 ZL2TR_Frmt_Aggr_SDU_n_SDU_Hdr_ primitive 3-21, 3-24 Aggr_SDU_Buff_ptr 3-24 Aggr_SDU_Buff_Size_B 3-24 mac_frame 3-24 mux_id 3-25 sap_value 3-24 sdu_type 3-24 ZL2TR_VAL_SDUTYPE_LLC1 324 ZL2TR_VAL_SDUTYPE_LLC2 324 SDU_User_Data_Offset_B 3-25 SDU_User_Data_Size_B 3-25 ZL2TR_Frmt_SDU_Hdr_ primitive 3-21, 3
Z Index PAM Programming Manual— 142482 Index- 6
