Synchronous Link Control (SLC) Programmer’s Guide DC 900-1564A Simpact, Inc.
Simpact, Inc. 9210 Sky Park Court San Diego, CA 92123 (619) 565-1865 Synchronous Link Control (SLC) Programmer’s Guide © 1998 Simpact, Inc. All rights reserved Printed in the United States of America This document can change without notice. Simpact, Inc. accepts no liability for any errors this document might contain. Freeway is a registered trademark of Simpact, Inc. All other trademarks and trade names are the properties of their respective holders.
Contents List of Figures 7 List of Tables 9 Preface 11 1 15 Introduction 1.1 1.2 Protocol Overview . . . . . . . . . . . . . . . Supported Hardware. . . . . . . . . . . . . . 1.2.1 Freeway Server . . . . . . . . . . . . . . 1.2.2 Embedded ICPs . . . . . . . . . . . . . 1.2.2.1 Windows NT (Intel or Alpha) . . . 1.2.2.2 OpenVMS. . . . . . . . . . . . . . 1.2.2.3 Digital UNIX . . . . . . . . . . . . 1.3 Available Programming Interfaces . . . . . . 1.3.1 Data Link Interface (DLI) . . . . . . . . 1.3.
Synchronous Link Control (SLC) Programmer’s Guide 2.2.6 3 Flow Control Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . Typical Sequence of Operations 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14 4 Initialization . . . . . . . . . . Attaching a Link . . . . . . . . Configuring an Attached Link . Binding an Attached Link . . . Sending an SLC Message . . . . Receiving an SLC Message . . . Sending an SLC Block . . . . . Receiving an SLC Block . . . .
Contents 4.4.4 Get Statistics Report 4.4.5 Get Status Report. . 4.5 Trace Category . . . . . . 4.5.1 Link Trace Data. . . 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header Formats 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9 5.10 5.11 5.12 5.13 5.14 5.15 5.16 6 57 Attach (All Access Modes) . . .
Synchronous Link Control (SLC) Programmer’s Guide 6.4.3.3 High-level Designators (HEX and HEN) . 6.4.3.4 Message Characteristics Identifier (MCI) . 6.4.3.5 Additional Characteristics Indicator (ACI) 6.5 Error Conditions . . . . . . . . . . . . . . . . . . . . 6.5.1 iICPStatus Field Codes . . . . . . . . . . . . . . 6.5.2 Receive Error Statistics . . . . . . . . . . . . . . A Include Files Index 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
List of Figures Figure 1–1: Freeway Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Figure 1–2: Embedded ICP Configuration . . . . . . . . . . . . . . . . . . . . . . . 17 Figure 3–1: Typical Commands and Responses . . . . . . . . . . . . . . . . . . . . 26 Figure 4–1: SLC Buffer Report “C” Structure . . . . . . . . . . . . . . . . . . . . . . 46 Figure 4–2: SLC Statistics Report “C” Structure . . . . . . . . . . . . . . . . . . . .
Synchronous Link Control (SLC) Programmer’s Guide 8 DC 900-1564A
List of Tables Table 4–1: Access Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Table 4–2: Command and Response Category Summary . . . . . . . . . . . . . . . 34 Table 4–3: SLC Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . 38 Table 5–1: Command and Response Category Summary . . . . . . . . . . . . . . . 58 Table 5–2: Comparison of Optional Arguments Usage (DLI versus Driver Calls) . . 61 Table 5–3: DLI_ICP_CMD_ATTACH Header Format . . .
Synchronous Link Control (SLC) Programmer’s Guide Table 6–1: Link Characteristics Identifier (LCI) on Low-level Networks. . . . . . . . Table 6–2: Additional Characteristics Indicator (ACI) and Extensions on Low-level Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Table 6–3: Link Characteristics Identifier (LCI) on High-level Networks . . . . . . . 90 Table 6–4: Message Characteristics Identifier (MCI) on High-level Networks . . . .
Preface Purpose of Document This document describes the operation and programming interface required to use Simpact’s Synchronous Link Control (SLC) protocol software running on a Simpact intelligent communications processor (ICP). The basic structure is described for header fields typically required by all SLC message formats.
Synchronous Link Control (SLC) Programmer’s Guide Chapter 5 is the SLC protocol reference providing specific header formats for all SLC commands and responses. Techpubs: Don’t delete the “Other Helpful Leslie — See Documents” about making (separate Chapter 6 of table at end cover error References). codessetonly Also “space (mergeon other below” first info into table = 0 pt. Chapter 2)? 7/2/98 Leslie: 7/2: We’re Creation saving this until last to Permanent decide.
Preface • • • • Leslie: There may be another socket interface document for Sm@rtServer (dc9001287)??? Getting Started with Freeway 1100 DC 900-1369 Getting Started with Freeway 2000/4000 DC 900-1330 Getting Started with Freeway 8800 DC 900-1552 Loopback Test Procedures DC 900-1533 Driver Installation and Programming Support • • • ICP2432 User’s Guide for Digital UNIX DC 900-1513 ICP2432 User’s Guide for OpenVMS Alpha DC 900-1511 ICP2432 User’s Guide for Windows NT DC 900-1510 Application P
Synchronous Link Control (SLC) Programmer’s Guide The term “SLC channel” refers to an ICP link configured on an SLC network connection. The term “SLC network connection” refers to the set of SLC channels (from 1 to 7) that together form the logical connection between the SLC protocol service on the ICP and an SLC network.
Chapter 1 Introduction Simpact provides a variety of user-programmable, wide-area network (WAN) connectivity solutions for real-time financial, defense, telecommunications, and processcontrol applications. Simpact software includes a wide variety of legacy and specialty protocols that run on Simpact’s intelligent communication processor (ICP) boards. The protocol software is independent of the hardware and operating system environment. Techpubs — This Section 1.
Synchronous Link Control (SLC) Programmer’s Guide 1.2.1 Freeway Server The Freeway server is a stand-alone box with pre-installed ICPs. It provides multiple data links and a variety of network services to LAN-based clients. Figure 1–1 shows a Freeway server configuration where the client application communicates with the Freeway ICPs using Simpact’s data link interface (DLI). Client applications can use either the DLI or socket interface, as described in Section 1.3.1 and Section 1.3.3.
1: Introduction Client Computer WAN Protocol Options SCADA Embedded ICP Defense Commercial X.25 Bisync HDLC . . . Simpact WAN Protocol Software Financial SWIFT CHIPS Telerate Telekurs Reuters 40+ Market Feeds . . . 3414 Application DLI n Industry Standard Bus … Application DLI 2 Simpact Driver Application DLI 1 AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA Figure 1–2: Embedded ICP Configuration 1.2.2.
Synchronous Link Control (SLC) Programmer’s Guide 1.2.2.3 Digital UNIX The supported programming interface for an embedded ICP in a Digital UNIX client computer is the driver interface, described in Section 1.3.2. The primary reference is the user’s guide for the applicable ICP (for example, the ICP2432 User’s Guide for Digital UNIX). 1.
1: Introduction • An example SLC test program and supporting DLI and TSI configuration files are provided with the SLC product, as listed below. To run the loopback test program, refer to the Loopback Test Procedures document (for the Freeway server) or the appropriate user’s guide for your embedded ICP and operating system (for example, the ICP2432 User’s Guide for Windows NT). Non-blocking I/O Test Program DLI Configuration File Name TSI Configuration File Name slcalp.c slcaldcfg slcaltcfg 1.3.
Synchronous Link Control (SLC) Programmer’s Guide 20 DC 900-1564A
Chapter 2 SLC Protocol Theory of Operation Simpact’s SLC protocol software running on the ICP provides the application with significant control over SLC operations while reducing the overall processing burden on the application. This chapter identifies the principal features of the SLC protocol that are under application control. 2.
Synchronous Link Control (SLC) Programmer’s Guide 2.2.1 Network-level Support When the application configures an ICP link for SLC protocol service, it specifies whether high-level network service or low-level network service is required. The application formats each outgoing message and interprets each incoming message, in conformance with the message format for the specified network-level service. 2.2.
2: SLC Protocol Theory of Operation An application can restrict the ICP to block-level retransmissions by setting the maximum number of message transmission attempts (N3) for the ICP link to 1. 2.2.5 Safe Store Support Safe store support allows the application to control when each received message is acknowledged, and to know when each transmitted message has been acknowledged. For outgoing traffic, the application assigns a message label to each transmitted message.
Synchronous Link Control (SLC) Programmer’s Guide 24 DC 900-1564A
Chapter 3 Typical Sequence of Operations 3.1 Initialization Section 1.3 on page 18 summarizes the programming interfaces available for use with the ICP. In all cases, the application first must perform any initialization required by the selected programming interface, and then must open an I/O path to the ICP prior to writing commands or reading responses to the protocol services on the ICP.
Synchronous Link Control (SLC) Programmer’s Guide Response Command Attach a Link DLI_ICP_CMD_ATTACH Data Transfer Preparation Sequence Attach Link Response DLI_ICP_CMD_ATTACH Configure an Attached Link DLI_PROT_CFG_LINK Configure Link Response DLI_PROT_CFG_LINK Bind an Attached Link DLI_ICP_CMD_BIND Bind Link Response DLI_ICP_CMD_BIND Send an SLC Message DLI_PROT_SEND_NORM_DATA or DLI_PROT_SEND_PRIOR_DATA Response to Confirm or Deny DLI_PROT_SAFE_STORE_ACK Receive an SLC Message DLI_PROT_SEND_NORM_
3: Typical Sequence of Operations 3.2 Attaching a Link The application must successfully attach an ICP link before it can configure, bind, read from, or write to that link. To attach a link, the application must perform the actions listed below. • The application writes a DLI_ICP_CMD_ATTACH command. This allocates the ICP link for application use under the rules for the access mode specified in the request, and associates a session with that link and access mode (defined in Table 4–1 on page 33).
Synchronous Link Control (SLC) Programmer’s Guide ured for SLC envelope service (default), then binding a link places it online for SLC block transfer. To bind a link, the application must perform the actions listed below. • The application writes a DLI_ICP_CMD_BIND command. • The application reads a DLI_ICP_CMD_BIND response with a status field that confirms or denies the request. 3.
3: Typical Sequence of Operations • The application writes a DLI_PROT_SAFE_STORE_ACK command that confirms receipt. Some restrictions might apply due to the specific configuration of the ICP link. 3.7 Sending an SLC Block If an ICP link is configured for SLC envelope service (default), then after the application attaches the ICP link with Master access mode and binds the link, it can send SLC blocks to the SLC network via the ICP link.
Synchronous Link Control (SLC) Programmer’s Guide • The application writes a DLI_PROT_CONTROL command. There is no acknowledgment; however, the application detects errors by reading a DLI_PROT_CONTROL response with a status that indicates the error. 3.
3: Typical Sequence of Operations DLI_PROT_GET_BUF_REPORT DLI_PROT_GET_LINK_CFG DLI_PROT_GET_SOFTWARE_VER DLI_PROT_GET_STATISTICS_REPORT DLI_PROT_GET_STATUS_REPORT • The application reads the report response of the same type. 3.13 Detaching a Link After the application attaches an ICP link, it can detach the link. Detaching a link relinquishes application access to the link.
Synchronous Link Control (SLC) Programmer’s Guide 32 DC 900-1564A
Chapter 4 Commands and Responses This chapter describes the commands written to the ICP and the responses received from the ICP. After you are familiar with the functionality, refer to Chapter 5 for detailed header formats to aid in writing application programs to interface to the SLC protocol. Table 4–1 defines the access modes required for using specific categories of commands and responses. The DLI_ICP_CMD_ATTACH command (Section 4.1.1 on page 35 and Section 5.
Synchronous Link Control (SLC) Programmer’s Guide Table 4–2: Command and Response Category Summary Category Code and Description Reference Section DLI_ICP_CMD_ATTACH (Section 4.1.1 on page 35) Access (Section 4.1) DLI_ICP_CMD_DETACH (Section 4.1.2 on page 35) Protocol Usage Write: Request SLC network access Read: Confirm/deny SLC network access Write: Relinquish SLC network access Read: Confirm/deny SLC network access relinquished DLI_ICP_CMD_BIND (Section 4.2.
4: Commands and Responses 4.1 Access Category The commands and responses in the Access category are used to establish access control sessions for a specified SLC network connection. Several access modes are supported: Master, Reader, Control, or Trace (refer back to Table 4–1 on page 33 for a summary). For each SLC network connection, only one application session is permitted per access mode. The DLI_ICP_CMD_ATTACH command establishes the access mode. Also see Section 6.
Synchronous Link Control (SLC) Programmer’s Guide 4.2 Link Category The commands and responses in the Link category are used to enable, disable or configure a specified SLC network connection. Only an application session with Master or Control access mode can use this category. 4.2.1 Bind The DLI_ICP_CMD_BIND command enables the SLC network connection to which the application has obtained access. The corresponding DLI_ICP_CMD_BIND response reports the success or failure of the request.
4: Commands and Responses The variable-length data area of the DLI_PROT_CFG_LINK command contains a specification list of one or more configuration options for the specified SLC network connection. The available configuration options are listed in Table 4–3. Each configuration option consists of a 16-bit unsigned integer option identifier followed by a 16-bit unsigned integer option value. Configuration options can appear in any order.
Synchronous Link Control (SLC) Programmer’s Guide Table 4–3: SLC Configuration Options Option Default Option Values Comments SLC_SERVICE_CFG ✓ SLC_ENVELOPE_SERVICE SLC_LOW_LEVEL_NETWORK SLC_HIGH_LEVEL_NETWORK SLC Service Support SLC_BLOCK_SCATTER _CFG ✓ 0 = Send message blocks serially 1 = Send message blocks in parallel on multiple channels Multi-block message channel scatter option SLC_BLOCK_ACK_CFG ✓ SLC_BLOCK_ACK_FAST SLC_BLOCK_ACK_SAFE Block-level acknowledgment timing.
4: Commands and Responses Table 4–3: SLC Configuration Options (Cont’d) Option Default Option Values Comments SLC_N1_CFG SLC_N1_DEFAULT 1…SLC_N1_MAXIMUM Refer to IATAa SLC_N2_CFG SLC_N2_DEFAULT 1…SLC_N2_MAXIMUM Refer to IATA SLC_N3_CFG SLC_N3_DEFAULT 1…SLC_N3_MAXIMUM Refer to IATA SLC_N4_CFG SLC_N4_DEFAULT 1…SLC_N4_MAXIMUM Refer to IATA SLC_N5_CFG SLC_N5_DEFAULT 1…SLC_N5_MAXIMUM Refer to IATA SLC_N6_CFG SLC_N6_DEFAULT 1…SLC_N6_MAXIMUM Refer to IATA SLC_T1_CFG SLC_T1_DEFAULT 1…
Synchronous Link Control (SLC) Programmer’s Guide 4.2.4 Control DLI_PROT_CONTROL can be used only when SLC protocol service is configured. It is not supported when SLC envelope service is configured. An application reads a DLI_PROT_CONTROL response when the ICP receives any link control block (LCB) that exerts stop/resume flow control. An application exerts operator control over SLC channel operation by writing a DLI_PROT_CONTROL command to the ICP.
4: Commands and Responses 4.3 Data Category The commands and responses in the Data category are used to transfer data on the specified SLC network connection. Only an application session with Master access mode can use this category. 4.3.1 Safe Store Acknowledgment DLI_PROT_SAFE_STORE_ACK can be used only when SLC protocol service is configured. It is not supported when SLC envelope service is configured. The header formats are detailed in Section 5.14 on page 78.
Synchronous Link Control (SLC) Programmer’s Guide 4.3.2 Normal Data DLI_PROT_SEND_NORM_DATA can be used only when SLC protocol service is configured. It is not supported when SLC envelope service is configured. The header formats are detailed in Section 5.12 on page 74. DLI_PROT_SEND_NORM_DATA contains an entire SLC low-priority message. The applica- tion writes this command to the ICP to transmit a message through the WAN interface to the SLC network.
4: Commands and Responses Table 5–16 on page 75 lists symbolic names for the DLI_PROT_SEND_NORM_DATA AML values that can appear in the iProtModifier field for both writes and reads. The validity of these values is influenced by both the network level and the message length. An AML for a single-block message can be used only with a message that fits within a single transmission block on the SLC network.
Synchronous Link Control (SLC) Programmer’s Guide When the application writes a DLI_PROT_SEND_PRIOR_DATA command, the ICP uses the iProtModifier field (AML value) to compute a corresponding message block identifier for each information block transmitted. The application reads a DLI_PROT_SAFE_STORE_ACK response when the ICP reports a corresponding acknowl- edgment.
4: Commands and Responses 4.3.4 Transparent Data DLI_PROT_SEND_TRANS_DATA can be used only when SLC envelope service is configured. It can not be used when SLC protocol service is configured. The header formats are detailed in Section 5.15 on page 80. DLI_PROT_SEND_TRANS_DATA contains a single SLC block. The application writes this command to the ICP to transmit a control block or an information block through the WAN interface to the SLC network.
Synchronous Link Control (SLC) Programmer’s Guide 4.4 Report Category The Report category is used to request specific reports from the ICP. 4.4.1 Get Buffer Report The DLI_PROT_GET_BUF_REPORT command requests the current ICP buffer usage. The ICP DLI_PROT_GET_BUF_REPORT response contains the requested buffer usage information. The header formats are detailed in Section 5.6 on page 68. When the application writes a DLI_PROT_GET_BUF_REPORT command to the ICP, it does so with a zero-length data area.
4: Commands and Responses 4.4.2 Get Link Configuration The DLI_PROT_GET_LINK_CFG command requests the current configuration of a specified SLC network connection. The ICP DLI_PROT_GET_LINK_CFG response contains the requested configuration information. The header formats are detailed in Section 5.7 on page 69. When the application writes a DLI_PROT_GET_LINK_CFG command to the ICP, it does so with a zero-length data area.
Synchronous Link Control (SLC) Programmer’s Guide the “C” structure format shown in Figure 4–2, where “UINT32” is a 32-bit unsigned integer data type.
4: Commands and Responses typedef struct slc_port_counts_struct { UINT32 change_cts; UINT32 change_dcd; UINT32 change_dsr; UINT32 change_dtr; UINT32 change_rts; UINT32 rcv_bcc; UINT32 rcv_frame_too_long; UINT32 rcv_no_buffer; UINT32 rcv_overrun; UNIT32 rcv_parity; UINT32 rcv_unexpected_dle; UINT32 rcv_unexpected_etb; UINT32 rcv_unexpected_syn; UINT32 reset_tsi_in; UINT32 reset_tsi_out; UINT32 xmt_timeout; UNIT32 xmt_underrun; } SLC_PORT_COUNTS_TYPE; Figure 4–4: SLC Port Counts “C” Structure } typedef st
Synchronous Link Control (SLC) Programmer’s Guide typedef struct slc_lsi_counts_struct { UINT32 ack; UINT32 nak_parity_bcc; UINT32 nak_sequence; UINT32 enquiry; UINT32 aml; UINT32 stop[8]; /* [0] = stop all; [1…7] = stop [1…7] UINT32 resume[8]; /* [0] = resume all; [1…7] = resume [1…7] } SLC_LSI_COUNTS_TYPE; */ */ Figure 4–6: SLC LSI Counts “C” Structure typedef struct slc_block_counts_struct { UINT32 link_control_blocks; UINT32 network_control_blocks; UINT32 normal_message_blocks; UINT32 priority_messa
4: Commands and Responses 4.4.5 Get Status Report The DLI_PROT_GET_STATUS_REPORT command requests operational status for a specified SLC network connection. The ICP DLI_PROT_GET_STATUS_REPORT response contains the requested status. The header formats are detailed in Section 5.10 on page 72. When the application writes a DLI_PROT_GET_STATUS_REPORT command to the ICP, it does so with a zero-length data area.
Synchronous Link Control (SLC) Programmer’s Guide typedef struct { UINT16 UINT16 UINT16 UINT16 UINT16 UINT16 UINT16 UINT16 } slc_msg_status_struct aml; /* See Table 5–16 and Table 5–18 */ blocks_acked; blocks_failed; blocks_pending; blocks_total; characters; reserved; state; /* SLC_MSG_AML_AVAILABLE, SLC_MSG_AML_FORBIDDEN, SLC_MSG_PENDING_TO_HOST, SLC_MSG_RECEIVING_FROM_NETWORK, SLC_MSG_REPORTING_TO_HOST, SLC_MSG_PENDING_TO_NETWORK, SLC_MSG_SENDING_TO_NETWORK, SLC_MSG_WAITING_NETWORK_ACK, or SLC_MSG_WAI
4: Commands and Responses 4.5 Trace Category 4.5.1 Link Trace Data The DLI_PROT_LINK_TRACE_DATA response contains one or more trace report entries. Each report entry contains an event_header_struct structure (Figure 4–11), followed by a 16-bit sample size, a 16-bit packet size, and an optional data trace field. Each trace report (Figure 4–12) begins on a 32-bit boundary within the data area.
Synchronous Link Control (SLC) Programmer’s Guide Figure 4–13 shows how to run the slc_trac trace program from the command-line prompt on a typical UNIX client. The program requires three parameters, which the operator provides either on the command-line itself, or as answers to questions displayed by the slc_trac program (as shown in bold type). The actual method for executing the slc_trac program on your client may differ from the method shown.
4: Commands and Responses TIME-STAMP EVENT STATUS 1240.705 1240.805 1241.005 1241.005 1241.005 1241.005 1241.015 1241.025 1241.040 1241.040 1241.155 1241.155 1241.270 1241.270 1241.280 1241.280 1241.305 1241.320 1241.440 1241.450 1241.555 1241.565 1241.565 1241.580 1241.580 1241.590 1241.805 1241.805 1241.910 1242.010 1242.
Synchronous Link Control (SLC) Programmer’s Guide TIME-STAMP EVENT STATUS 1289.710 TRACE ON 1289.810 DTR_1 ON 1290.010 DCD_1 ON 1290.010 DSR_1 ON 1290.010 RTS_1 ON 1290.010 CTS_1 ON 1290.020 XMT_1 5 ENQ 0000: 10 24 40 17 63 1290.030 RCV_1 5 ENQ 0000: 10 24 40 17 63 1290.045 RCV_1 5 ACK 0000: 10 21 40 17 66 1290.045 XMT_1 5 ACK 0000: 10 21 40 17 66 1290.
Chapter 5 Header Formats The application and the SLC protocol software on the ICP communicate by sending commands and responses. This chapter identifies the format of each command and response. Table 5–1 on page 58 gives an overview of the categories of commands and responses used by the SLC protocol. The individual header formats are presented alphabetically by command/response name in Section 5.1 through Section 5.16.
Synchronous Link Control (SLC) Programmer’s Guide Table 5–1: Command and Response Category Summary Category Access Link Data Report Code and Header Format Reference Section SLC Protocol Usage DLI_ICP_CMD_ATTACH (Section 5.1 on page 62) Write: Request SLC network access Read: Confirm/deny SLC network access DLI_ICP_CMD_DETACH (Section 5.5 on page 67) Write: Relinquish SLC network access Read: Confirm/deny SLC network access relinquished DLI_ICP_CMD_BIND (Section 5.
5: Header Formats typedef struct _DLI_OPT_ARGS { unsigned short usFWPacketType; /* Server’s packet type */ unsigned short usFWCommand; /* Server’s cmd sent or rcvd */ unsigned short usFWStatus; /* Server’s status of I/O ops*/ unsigned short usICPClientID; /* old su_id - not used */ unsigned short usICPServerID; /* old sp_id - not used */ unsigned short usICPCommand; /* ICP’s command.
Synchronous Link Control (SLC) Programmer’s Guide typedef struct { ICP_HDR PROT_HDR char } ICP_PACKET; _ICP_PACKET typedef struct { unsigned short unsigned short unsigned short _ICP_HDR icp_hdr; prot_hdr; *data; usICPClientID; usICPServerID; usICPCount; unsigned short usICPCommand; short iICPStatus; unsigned short usICPParms[3]; } ICP_HDR; typedef struct { unsigned short short unsigned short unsigned short unsigned short unsigned short unsigned short } PROT_HDR; /* Network-ordered header /* Host-ord
5: Header Formats Table 5–2: Comparison of Optional Arguments Usage (DLI versus Driver Calls) DLI_OPT_ARGS Field Name (DLI Calls) ICP_PACKET Field Name (Driver Calls) Typical SLC Protocol Value usFWPacketType usFWCommand Server Header Fields (network byte-order) FW_DATA Omitted FW_ICP_WRITE Omitted usFWStatus Omitted usICPClientID usICPServerID Omitted usICPCommand ICP Header Fields a icp_hdr.usICPClientID 0 icp_hdr.usICPServerID 0 icp_hdr.
Synchronous Link Control (SLC) Programmer’s Guide 5.1 Attach (All Access Modes) Table 5–3 shows the DLI_ICP_CMD_ATTACH header format. See Section 4.1.1 on page 35 for a functional description. There is no associated data area.
5: Header Formats 5.2 Bind (Master or Control Access Mode Only) Table 5–4 shows the DLI_ICP_CMD_BIND header format. See Section 4.2.1 on page 36 for a functional description. There is no associated data area.
Synchronous Link Control (SLC) Programmer’s Guide 5.3 Configure Link (Master or Control Access Mode Only) Table 5–5 shows the DLI_PROT_CFG_LINK header format. See Section 4.2.3 on page 36 for a functional description and information regarding the associated data area.
5: Header Formats 5.4 Control (Master or Control Access Mode Only) Table 5–6 shows the DLI_PROT_CONTROL header format. See Section 4.2.4 on page 40 for a functional description. There is no associated data area. Table 5–7 lists the supported operator control options.
Synchronous Link Control (SLC) Programmer’s Guide Table 5–7: DLI_PROT_CONTROL Operator Control Options SLC Command Code (iProtModifier Field) Operator Control Option Command Description SLC Channel Number (usProtCircuitID Field) Write Options: SLC_OPR_CHANNEL_START Set channel online SLC_OPR_CHANNEL_STOP Set channel offline SLC_OPR_IN_RESUME Report incoming data SLC_OPR_IN_STOP Discard all incoming data SLC_OPR_OUT_RESUME Transmit outgoing data SLC_OPR_OUT_STOP Hold outgoing data 0 = All cha
5: Header Formats 5.5 Detach (Master, Reader, Control or Trace Access Mode) Table 5–8 shows the DLI_ICP_CMD_DETACH header format. See Section 4.1.2 on page 35 for a functional description. There is no associated data area.
Synchronous Link Control (SLC) Programmer’s Guide 5.6 Get Buffer Report (Master, Reader, or Control Access Mode) Table 5–9 is the DLI_PROT_GET_BUF_REPORT header format. See Section 4.4.1 on page 46 for a functional description and the report format associated with the response.
5: Header Formats 5.7 Get Link Configuration (Master, Reader, or Control Access Mode) Table 5–10 is the DLI_PROT_GET_LINK_CFG header format. See Section 4.4.2 on page 47 for a functional description and the report format associated with the response.
Synchronous Link Control (SLC) Programmer’s Guide 5.8 Get Software Version (Master, Reader, or Control Mode) Table 5–11 shows the DLI_PROT_GET_SOFTWARE_VER header format. See Section 4.4.3 on page 47 for a functional description and the report format associated with the response.
5: Header Formats 5.9 Get Statistics Report (Master, Reader, or Control Mode) Table 5–11 shows the DLI_PROT_GET_STATISTICS_REPORT header format. See Section 4.4.4 on page 47 for a functional description and the report format associated with the response.
Synchronous Link Control (SLC) Programmer’s Guide 5.10 Get Status Report (Master, Reader, or Control Mode) Table 5–13 is the DLI_PROT_GET_STATUS_REPORT header format. See Section 4.4.5 on page 51 for a functional description and the report format associated with the response.
5: Header Formats 5.11 Link Trace Data (Trace Access Mode Only) Table 5–14 shows the read-only DLI_PROT_LINK_TRACE_DATA header format. See Section 4.5.1 on page 53 for a functional description and the data format associated with the response.
Synchronous Link Control (SLC) Programmer’s Guide 5.12 Normal Data (Master Access Mode Only) Table 5–15 shows the DLI_PROT_SEND_NORM_DATA header format. See Section 4.3.2 on page 42 for a functional description and information regarding the associated data area.
5: Header Formats Table 5–16: DLI_PROT_SEND_NORM_DATA AML Values AML Symbolic Name Acknowledge Message Label Description SLC_AML_A_ND Normal Data message SLC_AML_B_ND Normal Data message SLC_AML_C_ND Normal Data message SLC_AML_D_ND Normal Data message SLC_AML_E_ND Normal Data message SLC_AML_F_ND Normal Data message SLC_AML_G_ND Normal Data message SLC_AML_H_ND_SBM Normal Data single-block message SLC_AML_I_NDH_SBM Normal Data single-block message (high-level network only) SLC_AML_J_ND
Synchronous Link Control (SLC) Programmer’s Guide 5.13 Priority Data (Master Access Mode Only) Table 5–17 shows the DLI_PROT_SEND_PRIOR_DATA header format. See Section 4.3.3 on page 43 for a functional description and information regarding the associated data area.
5: Header Formats Table 5–18: DLI_PROT_SEND_PRIOR_DATA AML Values AML Symbolic Name Acknowledge Message Label Description SLC_AML_A_PD Priority Data message SLC_AML_B_PD Priority Data message SLC_AML_C_PD Priority Data message SLC_AML_D_PD Priority Data message SLC_AML_E_PD Priority Data message SLC_AML_F_PD Priority Data message SLC_AML_G_PD Priority Data message SLC_AML_H_PD_SBM Priority Data single-block message SLC_AML_I_PDH_SBM Priority Data single-block message (high-level network
Synchronous Link Control (SLC) Programmer’s Guide 5.14 Safe Store Acknowledgment (Master Access Mode Only) Table 5–19 shows the DLI_PROT_SAFE_STORE_ACK header format. See Section 4.3.1 on page 41 for a functional description. There is no associated data area.
5: Header Formats Table 5–20: DLI_PROT_SAFE_STORE_ACK AML Descriptors Bit Field Mask Name AMD_MASK_PROTECTION Bit Field Values AMD_FULL_PROTECTION AMD_NO_PROTECTION AMD_LIMITED_PROTECTION AMD_END_TO_END_PROTECTION AMD_MASK_PRIORITY AMD_LOW_PRIORITY AMD_HIGH_PRIORITY AMD_MASK_NETWORK AMD_LOW_NETWORK AMD_HIGH_NETWORK AMD_MASK_BLOCKS AMD_SINGLE_BLOCK AMD_2_BLOCKS … AMD_16_BLOCKS DC 900-1564A 79
Synchronous Link Control (SLC) Programmer’s Guide 5.15 Transparent Data (Master Access Mode Only) Table 5–21 shows the DLI_PROT_SEND_TRANS_DATA header format. See Section 4.3.4 on page 45 for a functional description and information regarding the associated data area.
5: Header Formats 5.16 Unbind (Master or Control Access Mode Only) Table 5–22 shows the DLI_ICP_CMD_UNBIND header format. See Section 4.2.2 on page 36 for a functional description. There is no associated data area.
Synchronous Link Control (SLC) Programmer’s Guide 82 DC 900-1564A
Chapter 6 Programming Considerations This chapter describes recommended strategies for programming applications to access SLC network connections using the SLC protocol software. 6.1 SLC Envelope Service versus SLC Protocol Service The SLC envelope service gives the application direct control over most ICP link operations, but requires the application to take complete responsibility for the results.
Synchronous Link Control (SLC) Programmer’s Guide Since the SLC protocol software supports multiple access modes simultaneously, the design of an application can be simplified by dividing its responsibilities among several independent processes. For example, a process under operator control could use SLC_CONTROL_MODE access to manage link configuration and operations. A second pro- cess could use SLC_READER_MODE access to gather and record statistics automatically.
6: Programming Considerations refer to the International Air Transport Association (IATA) document referenced on page 13 of the Preface. 6.4.1 SLC_ENVELOPE_SERVICE This level of SLC service provides transparent transmission and reception of SLC blocks without regard for content. This service requires that the client application provide the content of the SLC frame excluding the leading SYN and DLE control characters, the trailing ETB control character and the Block Check Character (BCC).
Synchronous Link Control (SLC) Programmer’s Guide DLI_PROT_SEND_PRIOR_DATA command allows iProtModifier field values of SLC_AML_A_PD through SLC_AML_G_PD for all message lengths, and restricts SLC_AML_H_PD_SBM to single block messages. The client application cannot send Link Control Blocks directly. However, the client can use the DLI_PROT_CONTROL command to request transmission of an SLC Link Control Block that contains a STOP flow or RESUME flow request.
6: Programming Considerations 6.4.2.2 Link Characteristics Identifier (LCI) The link characteristics identifier field is required in each SLC message sent or received on a low-level SLC network. Shown as the lci field in Figure 6–1 on page 86, the LCI appears as the first byte in the data area of each DLI_PROT_SEND_NORM_DATA or DLI_PROT_SEND_PRIOR_DATA command or response. Table 6–1 shows the internal for- mat of the LCI field. See also the slc_blks.h “C” include file.
Synchronous Link Control (SLC) Programmer’s Guide Table 6–2: Additional Characteristics Indicator (ACI) and Extensions on Low-level Networks Additional Characteristics Indicator (ACI) — One character per ACI or ACI Extension ACI_BASE_VALUE Always set ACI_EXTENSION Extension of ACI present when set ACI_CONTENT_MASK Mask to isolate (&) or ignore (&~) undefined portion of ACI 6.4.
6: Programming Considerations DLI_PROT_SAFE_STORE_ACK command causes the SLC protocol service to determine whether to transmit a Link Control Block that contains a corresponding Acknowledge Message Label (AML). 6.4.3.1 High-level Network Message Structure Figure 6–2 shows the structure of message header information within the data field of all DLI_PROT_SEND_NORM_DATA and DLI_PROT_SEND_PRIOR_DATA commands and responses when the SLC network connection is configured for high-level network service.
Synchronous Link Control (SLC) Programmer’s Guide DLI_PROT_SEND_PRIOR_DATA command or response. Table 6–3 shows the internal for- mat of the lci field. See also the slc_blks.h “C” include file.
6: Programming Considerations 6.4.3.4 Message Characteristics Identifier (MCI) The message characteristics identifier field is required in each SLC message sent or received on a high-level SLC network. Shown as the mci field in Figure 6–2 on page 89, the MCI contains one byte, and immediately follows the HEN. The MCI specifies the nature of the message information content and coding. The SLC protocol service on the ICP validates the coding of the MCI, but otherwise ignores the content of this field.
Synchronous Link Control (SLC) Programmer’s Guide 6.4.3.5 Additional Characteristics Indicator (ACI) The additional characteristics indicator field is optional in each SLC message sent and received on a high-level SLC network. If the LCI_ACI_PRESENT bit is set in the lci field, then the ACI is present, and is inserted between the mci field and the info field shown in Figure 6–2 on page 89. When present, the ACI and any ACI Extensions do not reduce the maximum message length.
6: Programming Considerations 6.5 Error Conditions 6.5.1 iICPStatus Field Codes The iICPStatus field serves two purposes. When the client application writes a command, this field identifies the client’s memory organization as Big Endian (0x0000) or Little Endian (0x4000). When the client application reads a response, this field contains either DLI_ICP_CMD_STATUS_OK (zero) or a negative error code.
Synchronous Link Control (SLC) Programmer’s Guide Table 6–6: Error Codes Reported in the iICPStatus Field (Cont’d) Error Code (iICPStatus field) Description SLC_ERR_AML_DUPLICATE Transmission of a previous message for the same Acknowledge Message Label (AML) has not net been completed or acknowledged. SLC_ERR_AML_VALUE The Acknowledge Message Label (AML) value specified in bits 0-7 of the iProtModifier field is not valid for the current network service level configuration.
6: Programming Considerations Table 6–6: Error Codes Reported in the iICPStatus Field (Cont’d) Error Code (iICPStatus field) SLC_ERR_LCI_HLD_MISSING or SLC_ERR_LCI_HLD_PRESENT Description In the required Link Characteristics Identifier field, the LCI_HLD_PRESENT bit is not consistent with the configured level of SLC network service.
Synchronous Link Control (SLC) Programmer’s Guide Table 6–6: Error Codes Reported in the iICPStatus Field (Cont’d) Error Code (iICPStatus field) Description SLC_ERR_SIZE The message is too large to be transmitted in sixteen or fewer SLC information blocks formatted in accordance with the current SLC_SERVICE_CFG configuration. SLC_ERR_TOO_LATE The DLI_PROT_SAFE_STORE_ACK command was received too late to send acknowledgment.
Appendix A Include Files Table A–1 summarizes the include files normally required by application programs for inclusion of the definitions of symbolically named values and data structures referenced in this document. Table A–1: SLC Include Files Include File DC 900-1564A Description slc_blks.h SLC protocol block structure and field definitions slc_defs.h Data symbol definitions slc_errs.h Error code symbol definitions slc_trac.h Data symbol definitions slc_typs.
Synchronous Link Control (SLC) Programmer’s Guide 98 DC 900-1564A
Index A Access category 35 attach 35 header format 62 detach 35 header format 67 summary 34, 58 Access modes 33 application simplification 83 session 35 Additional characteristics identifier (ACI) high-level network 92 low-level network 87 AML descriptors safe store acknowledgment 79 AML values normal data 75 priority data 77 Attach 27, 35 header format 62 session ID 27, 35, 62 Audience 11 B Bind 27, 36 header format 63 Block receive 29 send 29 Block counts C data structure 50 Buffer report 46 C data struc
Synchronous Link Control (SLC) Programmer’s Guide Configuration DLI protocol parameter 18 options 38 report 47 Configuration report header format 69 Configure link 27, 36 header format 64 table of options 38 Control 40 header format 65 network 30 operator 29 operator control options 66 Control access mode 33 Customer support 14 versus ICP packet 61 programming interface 18 protocol parameter 18 raw operation 18 protocol parameter 18 dlInit function 18 dlOpen function 18 dlRead function 18 dlWrite function
Index dlInit 18 dlOpen 18 dlRead 18 dlWrite 18 H Hardware supported 15 embedded ICP 16 Freeway server 16 Header ICP header fields 61 protocol header fields 61 server header fields 61 Header format 57 attach 62 bind 63 buffer report 68 configuration report 69 configure link 64 control 65 detach 67 link trace data 73 normal data 74 priority data 76 safe store acknowledgment 78 software version 70 statistics report 71 status report 72 transparent data 80 unbind 81 HEX and HEN high-level network 90 High-level
Synchronous Link Control (SLC) Programmer’s Guide server header 61 Network connection, definition 14 Network control 30 Network-level support 22 Normal data 42 AML values 75 header format 74 O OpenVMS embedded ICP 17 Operator control 29 options 66 Optional arguments C data structure 59 DLI 18, 61 Options configure link 38 operator control 66 Overview protocol 15 P Port counts C data structure 49 Priority data 43 AML values 77 header format 76 Product introduction 15 support 14 Programming data content depen
Index Revision history 14 S Safe store acknowledgment 41 AML descriptors 79 header format 78 Safe store support 23 Send block 29 message 28 Sequence of operations 25 attach 27 bind 27 configure link 27 control detect 30 exert 29 detach 31 diagram 26 initialization 25 receive block 29 receive message 28 reports 30 send block 29 send message 28 termination 31 unbind 30 Server header fields 61 network byte order 61 Service envelope 21, 85 envelope versus protocol service 83 high-level network 88 ACI 92 HEX an
Synchronous Link Control (SLC) Programmer’s Guide SLC network connection 14 Trace access mode 33 Trace category 53 link trace data 53 header format 73 summary 34, 58 Trace data 53 header format 73 Trace event header C data structure 53 Trace report C data structure 53 Transparent data 45 header format 80 U Unbind 30, 36 header format 81 W Windows NT embedded ICP 17 104 DC 900-1564A
Synchronous Link Control (SLC) Programmer’s Guide DC 900-1564A Customer Report Form We are constantly improving our products. If you have suggestions or problems you would like to report regarding the hardware, software or documentation, please complete this form and mail it to Simpact at 9210 Sky Park Court, San Diego, CA 92123, or fax it to (619)560-2838. If you are reporting errors in the documentation, please enter the section and page number.
Simpact, Inc.