BSCTRAN Programmer’s Guide DC 900-1406E Simpact, Inc.
Simpact, Inc. 9210 Sky Park Court San Diego, CA 92123 (619) 565-1865 BSCTRAN Programmer’s Guide © 1994 through 1999 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 Contents 3 List of Figures 5 List of Tables 7 Preface 9 1 BSCTRAN File Transfer Program Overview 1.1 1.2 2 15 Freeway Server versus Embedded ICP Version . . . . . . . . . . . . . . . BSCTRAN Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BSCTRAN Commands and Options 2.1 Specifying the Freeway Data Paths . . . . . . . . . . . . . . . . 2.1.1 Server Field in BSCTRAN Commands . . . . . . . . . . . 2.1.2 How the BSCTRAN Command Determines the Data Path 2.1.
BSCTRAN Programmer’s Guide 3 File Transfer Interface (BSCFTI) 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
List of Figures Figure 2–1: Example BSCTRAN Commands and Resulting Data Paths . . . . . . . . 23 Figure 2–2: Example of the HELP Command . . . . . . . . . . . . . . . . . . . . . . 26 Figure 7–1: DLI Configuration File for BSCTRAN . . . . . . . . . . . . . . . . . . . 104 Figure 7–2: TSI Configuration File for BSCTRAN. . . . . . . . . . . . . . . . . . . . 107 Figure 7–3: VMS DCL Command Procedure Example . . . . . . . . . . . . . . . . .
BSCTRAN Programmer’s Guide 6 DC 900-1406E
List of Tables Table 2–1: SHOW Command Output . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Table 2–2: RECEIVE File Open Options. . . . . . . . . . . . . . . . . . . . . . . . . 48 Table 5–1: Warnings Output by BSC File Transfer Program . . . . . . . . . . . . . . 94 Table 5–2: Error Return Codes Used by BSC File Transfer Program . . . . . . . . . . 95 Table 5–3: BSC ICP Error Return Codes. . . . . . . . . . . . . . . . . . . . . . . . .
BSCTRAN Programmer’s Guide 8 DC 900-1406E
Preface Purpose of Document This document describes the operation and programming interface required to use Simpact’s BSCTRAN product running on Simpact’s Freeway communications server or embedded ICP. Note In this document, the term “Freeway” can mean either a Freeway server or an embedded ICP. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface)).
BSCTRAN Programmer’s Guide • A Freeway communications server or an embedded ICP that runs the BSC communications software • VAX/VMS or UNIX client computer that runs the following: • • Note TCP/IP (for a Freeway server) Data link interface (DLI) BSCTRAN currently supports VMS and UNIX only. Organization of Document Chapter 1 gives an overview of the BSCTRAN File Transfer program. Chapter 2 describes the User Interface (BSCTRAN) and gives details on using each of the commands and their options.
Preface 3/3/99 Leslie: Temporarily remove 1332, 1532, 1541, and 1543 (post-layoffs) Simpact References The following documents provide useful supporting information, depending on the customer’s particular hardware and software environments. Most documents are available on-line at Simpact’s web site, www.simpact.com.
BSCTRAN Programmer’s Guide Embedded ICP 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 OpenVMS Alpha (DLITE Interface) DC 900-1516 ICP2432 User’s Guide for Windows NT DC 900-1510 ICP2432 User’s Guide for Windows NT (DLITE Interface) DC 900-1514 Application Program Interface (API) Programming Support • • • Freeway Data Link Interface Reference Guide DC 900-1385 Freewa
Preface • • • • SIO STD-1300 Programmer’s Guide DC 908-1559 X.25 Call Service API Guide DC 900-1392 X.25/HDLC Configuration Guide DC 900-1345 X.25 Low-Level Interface DC 900-1307 Document Conventions The term “Freeway” refers to any of the Freeway server models (for example, Freeway 1100/1150/1200/1300, Freeway 2000/4000, or Freeway 8800), or to the embedded ICP product (for example, the embedded ICP2432). Physical “ports” on the ICPs are logically referred to as “links.
BSCTRAN Programmer’s Guide Customer Support If you are having trouble with any Simpact product, call us at 1-800-275-3889 Monday through Friday between 8 a.m. and 5 p.m. Pacific time. You can also fax your questions to us at (619)560-2838 or (619)560-2837 any time. Please include a cover sheet addressed to “Customer Service.” We are always interested in suggestions for improving our products. You can use the report form in the back of this manual to send us your recommendations.
Chapter 1 BSCTRAN File Transfer Program Overview Note In this document, the term “Freeway” can mean either a Freeway server or an embedded ICP. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface)). BSCTRAN is a client-resident application that interfaces with the BSC 2780/3780 software on Freeway.
BSCTRAN Programmer’s Guide 1.1 Freeway Server versus Embedded ICP Version The Freeway server version of BSCTRAN uses the Freeway data link interface (DLI) application program interface (API). Its execution requires both a DLI configuration file (dlitrancfg) and a transport subsystem interface (TSI) configuration file (tsitrancfg). When BSCTRAN is executed, binary versions of dlitrancfg and tsitrancfg are read and the information used to manage the session(s) with Freeway.
1: BSCTRAN File Transfer Program Overview The five modules are as follows: 1. User-interactive or Batch Program (BSCTRAN) 2. File Transfer Interface (BSCFTI) 3. Record Transfer Interface (BSCRTI) 4. Freeway Conversion Module (BSCFWY) 5. DLI Interface (ICPDLI) The BSCTRAN program runs as an executable image and accepts commands from a terminal or a command file. BSCTRAN can be run in a batch or an interactive environment.
BSCTRAN Programmer’s Guide 18 DC 900-1406E
Chapter 2 Note BSCTRAN Commands and Options In this document, the term “Freeway” can mean either a Freeway server or an embedded ICP. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface)). The BSCTRAN program accepts command strings interactively from a terminal or in batch mode by means of a DCL command procedure.
BSCTRAN Programmer’s Guide RECEIVE Receive a file from a remote BSC station. EXIT Terminate processing. Comments are allowed on the BSCTRAN command line. Comments begin with an exclamation mark (!) and may be useful for clarifying the actions in a command procedure. See Chapter 7 for an example of a command procedure. 2.1 Specifying the Freeway Data Paths BSCTRAN is a Simpact data link interface application (DLI for a Freeway server or DLITE for an embedded ICP).
2: BSCTRAN Commands and Options 2.1.1 Server Field in BSCTRAN Commands Many of the BSCTRAN commands include a server parameter. Note that this parameter contains a pointer that allows the Freeway software to determine a DLI session name and thus a board number and a link number, by referencing the configuration files. Consider the following example. Suppose you want to use the SHOW command to display the configuration of a particular link on a particular ICP.
BSCTRAN Programmer’s Guide For a detailed view of a sample Freeway server dlitrancfg file, refer to Section 7.1 on page 104. Note how in our example, the session definition properly indicates that the desired ICP board number is 0 and the desired link number is 2. Also note that the Transport parameter indicates a connection name of bsc0. The Freeway software uses the connection name to find the server name.
2: BSCTRAN Commands and Options Example BSCTRAN Commands DLI Configuration File (dlitrancfg) TSI Configuration File (tsitrancfg) (Freeway Server Only) SHOW 2 FWY0_0 Displays configuration for link 2 of board 0 SHOW 2 FWY0_1 Displays configuration for link 2 of board 1 FWY0B0L2 bsc0 server = "freeway0"; Transport = "bsc0"; BoardNo = "0"; PortNo = "2"; FWY0B1L2 Transport = "bsc1"; BoardNo = "1"; PortNo = "2"; bsc1 server = "freeway0"; 310 1 Figure 2–1: Example BSCTRAN Commands and Resulting Data
BSCTRAN Programmer’s Guide 2.1.3 Important Considerations for Freeway Server Note the following important considerations before using BSCTRAN in a Freeway server. These notes assume that you have read the previous sections. • Check to make sure that the supplied DLI and TSI configuration files, dlitrancfg and tsitrancfg, are set up to meet the needs of your system.
2: BSCTRAN Commands and Options 2.1.4 BSCTRAN Logging 2.1.4.1 VMS Logical Names and Logging BSCTRAN supports the use of VMS logical names for the link number and server name. The maximum length of a logical name is 10 characters. A logical name may be defined in any VMS logical name table that is included in the LNM$FILE_DEV logical name table search list. (This list usually includes the process, job, group, and system tables.) If a server logical name is used, it will be prefixed to all log messages.
BSCTRAN Programmer’s Guide 2.2 HELP Command The HELP command displays the format for all legal BSCTRAN commands. It takes no argument. Figure 2–2 is an example of the HELP command. In the figure, square brackets [ ] are used to indicate optional fields for commands. After the device name and link number have been established, the use of brackets is optional on subsequent commands. Note The DEFAULT command options [/[NO]PRINT], [/[NO]BATCH], and [/[NO]LOG[=n]] do not apply to UNIX.
2: BSCTRAN Commands and Options Note The server parameter is not the server name, but is a pointer to the server name. It is important that you read Section 2.1 on page 20 to understand the server parameter. Note that the ICP number is appended to the server parameter using an underscore character. If there are multiple boards, the ICP number determines which ICP board to connect to. If desired, a dash (–), forward slash (/), or equal sign (=) can be used in place of the underscore.
BSCTRAN Programmer’s Guide 2.3 SHOW Command The SHOW command has the following format: SHOW link# server[_ICP#] [/DEFAULT] [/STATS] [/CLEAR] The SHOW command displays the current configuration of the link (link#) on the server pointed to by the server parameter. It is important that you read Section 2.1 on page 20 to understand the server parameter. Table 2–1 is an example of the SHOW command output indicating the default BSC link configurations immediately after downloading the BSC software to the ICP.
2: BSCTRAN Commands and Options See the BSC Programmer’s Guide for a complete description of ICP link configuration parameters. The SHOW command options are as follows: /DEFAULT This option displays the current values of the DEFAULT command options. Because these are global options, no link# or server parameter is required for this command.
BSCTRAN Programmer’s Guide BSC> SHOW 2 spot_1 /STATS /CLEAR ! Statistics before clearing 30 Recv Recv Recv Recv Recv Recv BSC> CURRENT STATISTICS FOR data messages = 2 Xmit blocks = 9 Xmit NAKs = 0 Xmit buffer errors = 0 Xmit BCC errors = 0 Recv overrun errors = 0 SHOW /STATS ! The LINK #2: data messages blocks NAKs buffer errors parity errors Recv Recv Recv Recv Recv Recv CURRENT STATISTICS FOR data messages = 0 Xmit blocks = 0 Xmit NAKs = 0 Xmit buffer errors = 0 Xmit BCC errors = 0 Recv overrun er
2: BSCTRAN Commands and Options 2.4 SET Command The SET command has the following format: SET link# server[_ICP#] [/PARn[=d]] [/PARn[=d]...] [/START] [/STOP] The SET command sets up the configurations of the link (link#) on the ICP board (ICP#). The SET command options are as follows: /PARn[=d] This option specifies the value of configuration parameter n, where n = 1 through 30, and d = 0 through the maximum allowed value for the particular parameter n.
BSCTRAN Programmer’s Guide Caution /STOP Be aware of the implications of using the SET /LOCKSTART command. After a link is enabled with /LOCKSTART, it remains enabled (even if BSCTRAN terminates) until the link is disabled with a SET /STOP command. A link that remains enabled after termination of a BSCTRAN process (due to a LOCKSTART) continues receiving messages into its data queues until it either runs out of buffers, or until a new BSCTRAN process references (attaches) the same link.
2: BSCTRAN Commands and Options 2.5 DEFAULT Command The DEFAULT command has the following format: DEFAULT [/FILE=filename] [/FIXED] [/BINARY] [/RECL=n] [/ESCAPE] [/FORTRAN] [/[NO]PRINT] [/[NO]BATCH] [/[NO]LOG[=n]] [/[NO]DLOG] [/[NO]DELETE] [/[NO]SAFE] [/[NO]ABORT] [/RECORDS=[2780,3780]] [/BUFSIZE=n] Note The DEFAULT command options [/[NO]PRINT] [/[NO]LOG[=n]] do not apply to UNIX.
BSCTRAN Programmer’s Guide /[NO]PRINT If this VMS option is enabled, each received file will be automatically queued to the system printer after the file is closed. The default is /NOPRINT. /[NO]BATCH If this VMS option is enabled, each received file will be automatically queued to the system batch queue after the file is closed. The default is /NOBATCH.
2: BSCTRAN Commands and Options /[NO]DLOG If this option is enabled, all errors, warnings, and transmission statistics will be logged to a disk log file. The default is /NODLOG. The disk log file name has the following format: SSSSSSSSSS_B_N_MMMDD.LOG where: SSSSSSSSSS = server parameter. It is important that you B N MMMDD read Section 2.1 on page 20 to understand this parameter. = ICP board # = Link # = Month/Day Each different device/link pair will have a separate log file.
BSCTRAN Programmer’s Guide The abort is performed at the BSCFTI level so that users writing their own applications can control this option by calling the BSCDFAULT procedure. The default is /NOABORT. /[NO]SAFE If this option is enabled, BSCTRAN will send a Safe Store Acknowledgment to the ICP upon successful closing of any received file. If the file close is unsuccessful, BSCTRAN will send a Safe Store Negative Acknowledgment.
2: BSCTRAN Commands and Options To send transparent 2780 records, BSCTRAN prefixes each record with the count. Records are accumulated into the BSCTRAN write buffer without splitting records. Blocks are written to the ICP as command codes 22 and 23. The ICP transmission block should be equal to or greater than the maximum record size + 2. Note The SEND /CARD option is not supported for transparent 2780.
BSCTRAN Programmer’s Guide Cautions: 1. The default ICP message buffer size for BSCTRAN is 1024 bytes. When the BSCTRAN program is run, it sends a buffer configuration command to set the same size buffers on the ICP, only if this size is changed from 1024 with the /DEFAULT command. There are two other buffer pools that must be configured for BSCTRAN to work correctly. One buffer pool is used with the Freeway DLI routines. The size of these buffers is set in the DLI configuration file.
2: BSCTRAN Commands and Options 2.6 DIAL Command The DIAL command has the following format: DIAL link# server[_ICP#] [/STRING=s] [/CONFIG=s] [/RESPONSE] [/DTIME=h:m:s] The DIAL command sends the autodial and/or modem configuration strings to the ICP to communicate with the modem type specified by ICP configuration option 35 for performing autodial operations on the link (link#) of the ICP board (ICP#). The link must be disabled or the DIAL command will be rejected.
BSCTRAN Programmer’s Guide /DTIME=h:m:s This option is the timeout specification (default time is 1 minute). This is the maximum time that BSCTRAN will wait for the ICP to return the modem response. If timeout occurs, BSCTRAN will abort or return the user to the BSC prompt, depending on the setting of the global DEFAULT /ABORT option.
2: BSCTRAN Commands and Options 2.7 SEND Command The SEND command has the following format: SEND filename link# server[_ICP#] [/DTIME=h:m:s] [/BINARY] [/TRANS] [/CARD] [/NOTEOF] The SEND command sends the file (filename) for transmission on the link (link#) of the ICP board (ICP#).
BSCTRAN Programmer’s Guide Caution If the user needs to ensure that binary data records (sent without the /TRANS option) are not concatenated when sent by the ICP, message blocking should be set to off. /TRANS This option specifies that BSCTRAN will instruct the ICP to send the file in transparent mode. This option is necessary to send files such as object or executable images which may contain control characters that might be misinterpreted by the BSC communication protocol.
2: BSCTRAN Commands and Options 3. Refer to the BSC Programmer’s Guide for information regarding the relationship between transparent data and the ICP data translation setting. /CARD This option sends the file in 80-character card image format. Records are split or padded with spaces if necessary. Many IBM systems require incoming data to be in this format. This option is not supported for transparent 2780 records.
BSCTRAN Programmer’s Guide 2.8 RECEIVE Command The RECEIVE command has the following format: RECEIVE filename link# server[_ICP#] [/DTIME=h:m:s] [/BINARY] [/RECL=n] [/FIXED] [/FORTRAN] [/ESCAPE] The RECEIVE command creates the file (filename), receives records from the link (link#) on the ICP (ICP#), and writes them into the file until the last record (the ETX block) is received. Then the file is closed.
2: BSCTRAN Commands and Options The BSC File Transfer program displays the state changes of the file transfer with the following statements: spot_1_3: 10-APR-1989 10:40:09.68 spot_1_3: 10-APR-1989 10:40:09.88 Receiving Recv Complete TXT.RCV TXT.RCV=18 Records The RECEIVE command options are as follows: /DTIME=h:m:s This option is the timeout specification (default time is 1 minute). This is the maximum time BSCTRAN will wait for the data records from the ICP.
BSCTRAN Programmer’s Guide /FIXED This option specifies that the file is opened with fixed-length record format, where the length is determined by the /RECL option (default = 512). If incoming records are not already in the specified fixed-length format, BSCTRAN will continue reading records from the ICP, concatenating and splitting records as necessary to accumulate the required length. The last record will be padded with ASCII spaces if necessary.
2: BSCTRAN Commands and Options /ESCAPE If this option is specified, the BSC File Transfer program looks for a two-character forms-control escape sequence at the beginning of each incoming data record. The escape character is deleted and the forms control character is converted to the equivalent RMS print file carriage control.
BSCTRAN Programmer’s Guide Table 2–2: RECEIVE File Open Options BSCTRAN Option RMS Record Format RMS Record Attributes (Default) Variable Carriage return carriage control /FIXEDa Fixed None /BINARY Variable None /FORTRAN VFCb Print file carriage control /ESCAPE VFC Print file carriage control a /FIXED takes precedence over /BINARY for record format. b VFC record format = variable with fixed-length control.
2: BSCTRAN Commands and Options 2.9 EXIT Command The EXIT command has the following format: EXIT The EXIT command causes the BSC File Transfer program to exit and return the user to the system command level. All active links are disabled with the EXIT command.
BSCTRAN Programmer’s Guide 50 DC 900-1406E
Chapter 3 Note File Transfer Interface (BSCFTI) In this document, the term “Freeway” can mean either a Freeway server or an embedded ICP. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface)). The BSC File Transfer Interface consists of a set of procedure calls that are used by the BSC User Interface (BSCTRAN) to send and receive files from Freeway.
BSCTRAN Programmer’s Guide 3.1 BSCDFAULT Procedure Calling Sequence BSCDFAULT (fname, fixed, binary, fortran, escape, recl, bufsize, print, batch, log, dlog, delete, abort, safe, rec3780) Note The print, batch, and log arguments of the BSCDEFAULT procedure do not apply to UNIX. Procedures Called None Functions 1. Reconfigures the BSCRTI global bscdefault structure (refer to the C typedef BSCDFLT structure in the BSCTRAN.INC include file).
3: File Transfer Interface (BSCFTI) record separator characters, but by recl length only. A non-zero value is treated as true. fortran This is a pointer to an integer. It is a longword containing a boolean flag. If the flag is true, BSCRECV will look for Fortran forms-control characters at the beginning of each incoming record. A non-zero value is treated as true. escape This is a pointer to an integer. It is a longword containing a boolean flag.
BSCTRAN Programmer’s Guide OPER1 through OPER12). Log messages will be output to the operator console. A zero value will disable operator console logging. dlog This is a pointer to an integer. It is a longword containing a boolean flag. If the flag is true, log messages will be output to a disk log file. A non-zero value is treated as true. delete This is a pointer to an integer. It is a longword containing a boolean flag.
3: File Transfer Interface (BSCFTI) 3.2 BSCDIAL Procedure Calling Sequence ReturnCode = BSCDIAL (lnum, server, dial, config, dtime, response, display) Procedures Called BSCDAS, BSCASL, BSCMODEM, BSCRESET, and BSCFWY Functions 1. Verifies legal parameters. 2. If there is a change in the server name or ICP device, calls BSCASL to assign input and output channels. 3.
BSCTRAN Programmer’s Guide server This is a pointer to a descriptor. It is a character string containing the server name. An ICP board number may be appended to the server name with an underscore character; otherwise, the ICP board number is assumed to be 0. The maximum length is ten characters. dial This is a pointer to a descriptor. It is a character string containing the autodial string. The maximum length is 256 characters. config This is a pointer to a descriptor.
3: File Transfer Interface (BSCFTI) 3.3 BSCLOG Procedure Calling Sequence BSCLOG (lnum, display, message) Procedures Called None Functions 1. Builds current device name, link number (lnum), system time, and text of message into a log message. 2. Checks BSCTRAN global options (maintained by procedure BSCDFAULT) for operator console and disk file logging. If enabled, these functions are performed. 3. If display is true, outputs log message to the system output device.
BSCTRAN Programmer’s Guide 3.4 BSCRECV Procedure Calling Sequence ReturnCode = BSCRECV (fname, lnum, server, dtime, fixed, recl, binary, forms, display) Procedures Called BSCDAS, BSCASL, BSCREAD, and BSCRESET Functions 1. If there is a change in the server name or ICP device, calls BSCASL to assign input and output channels. 2. Opens the file (fname) with the specified format. 3. Calls BSCREAD to get a record from the ICP link (lnum). 4. Performs forms-control translation if required. 5.
3: File Transfer Interface (BSCFTI) lnum This is a pointer to an integer. It is a longword containing the link number. server This is a pointer to a descriptor. It is a character string containing the server name. An ICP board number may be appended to the server name with an underscore character; otherwise, the ICP board number is assumed to be 0. The maximum length is ten characters. dtime This is a pointer to a descriptor.
BSCTRAN Programmer’s Guide Return Codes See Table 5–2 on page 95 for full descriptions of the error return codes.
3: File Transfer Interface (BSCFTI) 3.5 BSCSAFE Procedure Calling Sequence ReturnCode = BSCSAFE (lnum, code) Procedures Called BSCRESET and BSCFWY Functions • If code is true, sends a Safe Store Acknowledgment to the ICP and waits for the response. • If code is false, sends a Safe Store Negative Acknowledgment to the ICP (no response). Arguments lnum This is a pointer to an integer. It is a longword containing the link number. code This is an integer flag.
BSCTRAN Programmer’s Guide 3.6 BSCSEND Procedure Calling Sequence ReturnCode = BSCSEND (fname, lnum, server, dtime, trans, binary, card, noteof, display, dak) Procedures Called BSCDAS, BSCASL, BSCWRIT, BSCRESET, and BSCFWY Functions 1. Configures the DAK node to dak and issues a Flush Queue command to the ICP. 2. Opens the file (fname). 3. If there is a change in the server name or ICP device, calls BSCASL to assign input and output channels. 4.
3: File Transfer Interface (BSCFTI) 7. Closes the file. 8. Logs the transmission statistics. Arguments fname This is a pointer to a descriptor. It is a character string containing the file specification of the file to be transmitted. The maximum length is 255 characters. lnum This is a pointer to an integer. It is a longword containing the link number. server This is a pointer to a descriptor. It is a character string containing the server name.
BSCTRAN Programmer’s Guide noteof This is a pointer to an integer. It is a longword containing the noteof indicator. If the flag is true, the last block is sent as ETB rather than ETX. display This is a pointer to an integer. It is a longword containing the boolean flag for state change display. This flag is used to conditionally log the transmission state changes to the system output device. dak This is a longword containing the DAK node indicator.
3: File Transfer Interface (BSCFTI) 3.7 BSCSET Procedure Calling Sequence ReturnCode = BSCSET (lnum, server, lconf, start) Procedures Called BSCDAS, BSCASL, BSCRESET, and BSCFWY Functions 1. If there is a change in the server name or ICP device, calls BSCASL to assign input and output channels. 2. Sends the requested configuration(s) to the ICP for link (lnum) based on parameters lconf and start.
BSCTRAN Programmer’s Guide that follows. For link configuration, the data block consists of a variable number of two-word configuration parameter/value pairs. For autodial, the data block contains the NULL-terminated autodial command string, filled in as bytes. The data structure is defined by the following C typedef (refer to the BSCTRAN.
3: File Transfer Interface (BSCFTI) 3.8 BSCSHOW Procedure Calling Sequence ReturnCode = BSCSHOW (lnum, server, lconfig, clear_stats) Procedures Called BSCDAS, BSCASL, BSCRESET, and BSCFWY Functions 1. If there is a change in the server name or ICP device, calls BSCASL to assign input and output channels. 2. If the clear_stats flag is 1, issues a Clear Statistics command (command code 4) for link (lnum) to the ICP, waits for the statistics report, and returns immediately.
BSCTRAN Programmer’s Guide lconfig This is a pointer to a data structure to receive link configuration/status. The data structure is defined by the following C typedef (refer to the BSCTRAN.
3: File Transfer Interface (BSCFTI) Return Codes See Table 5–2 on page 95 for full descriptions of the error return codes.
BSCTRAN Programmer’s Guide 3.
3: File Transfer Interface (BSCFTI) The following FORTRAN example program calls BSCRECV (the SYS$ASCTIM call applies to VMS only.): program recv implicit none character*20 name_of_file /‘filetest.
BSCTRAN Programmer’s Guide !-----------------------------------------------------------------! START OF CODE !-----------------------------------------------------------------! ! C Receive file from ICP C-----------------------------------------------------------------fname = name_of_file bfname(13) = 0 ! null terminate string lnum = 3 server = ‘spot’ dtime = ‘0000 00:05:00’ recl = 80 ! record length binary = 0 ! include rec separators forms = 0 ! no forms control display = 1 ! display of state of changes
Chapter 4 Note Record Transfer Interface (BSCRTI) In this document, the term “Freeway” can mean either a Freeway server or an embedded ICP. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface)). The Record Transfer Interface consists of a set of procedure calls that are used by the BSC File Transfer Interface (BSCFTI) to send and receive records from the ICP.
BSCTRAN Programmer’s Guide 4.1 BSCASL Procedure This procedure must be executed before records can be read from or written to the ICP. It must be called on startup or when changing the link number, ICP number, or server name. Applications calling BSCRTI procedures (such as BSCREAD or BSCWRIT) must call BSCDAS or BSCASL when changing the link number. BSCFTI procedures (BSCDIAL, BSCRECV, BSCSEND, BSCSET, and BSCSHOW) automatically monitor changes in link number.
4: Record Transfer Interface (BSCRTI) name with an underscore character; otherwise, the ICP board number is assumed to be 0. The maximum length is ten characters. Return Codes See Table 5–2 on page 95 for full descriptions of the error return codes.
BSCTRAN Programmer’s Guide 4.2 BSCDAS Procedure This procedure should be executed before calling BSCASL to change the link number, ICP number, or server name. Calling Sequence ReturnCode = BSCDAS () Procedures Called BSCFWY Function 1. Deassigns current ICP input and output channels and cancels any outstanding I/O. Arguments None Return Codes See Table 5–2 on page 95 for full descriptions of the error return codes.
4: Record Transfer Interface (BSCRTI) 4.3 BSCMODEM Procedure This procedure can be called only after the ICP has been assigned (see the BSCASL procedure, Section 4.1 on page 74). This procedure issues an Autodial Start command (command code 38) or Modem Configuration command (command code 39) to the ICP and waits for a response. Calling Sequence ReturnCode = BSCMODEM (rdblock, string, dtime, code) Procedures Called BSCRESET and BSCFWY Functions 1. Verifies I/O channel assignment and legal parameters. 2.
BSCTRAN Programmer’s Guide dtime This is a pointer to a descriptor. It is a character string containing the timeout value in the following time string format: VMS format: UNIX format: code dddd hh:mm:ss hh:mm:ss This is an integer. It is a longword containing the appropriate command code, either Autodial Start (command code 38) or Modem Configuration (command code 39). Return Codes See Table 5–2 on page 95 for full descriptions of the error return codes.
4: Record Transfer Interface (BSCRTI) 4.4 BSCREAD Procedure This procedure can be called only after the server, ICP, and link number have been assigned (see Section 4.1 on page 74). Calling Sequence ReturnCode = BSCREAD (rdblock, recbuf, recl, lastrec, fixed, binary, forms, dtime) Procedures Called BSCRESET and BSCFWY Functions 1. If the read block (rdblock) is empty, reads in another read block from the ICP.
BSCTRAN Programmer’s Guide Arguments rdblock This is a pointer to a data structure of type TRANBUF. It receives the data block from the ICP. See Section 4.8 on page 91 or the BSCTRAN.INC include file for details of the data structure. recbuf This is a pointer to a descriptor. It is a character string to receive the data record from the ICP. The maximum length is 4096 bytes. The descriptor length field should be cleared before calling BSCREAD.
4: Record Transfer Interface (BSCRTI) are not deblocked using record separator characters, but by the length of the ICP read block or recl, whichever is smaller. forms This is a pointer to an integer. It is a longword indicating the type of forms control, FORTRAN, ESCAPE, or NONE (default), defined as 1, 2, and 0, respectively, in the BSCTRAN.INC include file.
BSCTRAN Programmer’s Guide Caution The RCUNR return code from BSCREAD is treated as a non-fatal error. User applications that call this procedure should handle the unexpected response during record processing or call BSCRESET. The C code fragment shown below illustrates the proper use of BSCREAD after an unexpected data response is received while calling BSCWRIT. See also the example following the BSCWRIT procedure in Section 4.7 on page 87.
4: Record Transfer Interface (BSCRTI) DC 900-1406E /* Write the record in rd_recbuf to the receive file. */ } while (!lastrec); /* lastrec flag set by BSCREAD . /* After the last record is received, close the file.
BSCTRAN Programmer’s Guide 4.5 BSCRESET Procedure This procedure is called when any error occurs that prevents the file transfer operation from completing normally. Calling Sequence BSCRESET () Procedures Called BSCFWY Functions 1. Cancels outstanding I/O. 2. Initializes all flags and counters used by BSCREAD and BSCWRIT.
4: Record Transfer Interface (BSCRTI) 4.6 BSCTRACE Procedure This procedure can be called only after the ICP has been assigned (see the BSCASL procedure, Section 4.1 on page 74). This procedure is not used by BSCTRAN, but can be called by any user application linked with BSCRTI.OBJ. Calling Sequence ReturnCode = BSCTRACE (rdblock, dtime, start, stop, data) Procedures Called BSCRESET and BSCFWY Functions 1. Verifies I/O channel assignment and legal parameters. 2.
BSCTRAN Programmer’s Guide dtime This is a pointer to a descriptor. It is a character string containing the timeout value in the following time string format: VMS format: UNIX format: start dddd hh:mm:ss hh:mm:ss This is an integer. It is a longword containing the boolean flag. If the flag is true, BSCTRACE issues a start trace command to the ICP and waits for a start trace acknowledge. stop This is an integer. It is a longword containing the boolean flag.
4: Record Transfer Interface (BSCRTI) 4.7 BSCWRIT Procedure This procedure can be called only after the ICP has been assigned (see the BSCASL procedure, Section 4.1 on page 74). The caller has total responsibility for insertion of record separators or transparent 2780 count characters, and ensuring that the total ICP writeblock size does not exceed the value of the DEFAULT /BUFSIZE option (default is 1024).
BSCTRAN Programmer’s Guide Arguments rdblock This is a pointer to a data structure of type TRANBUF. It receives the data acknowledgment block from the ICP. See Section 4.8 on page 91 or the BSCTRAN.INC include file for details of the data structure. recbuf This is a pointer to a descriptor. It is a character string containing the record to be sent. The maximum length is 4096 bytes. The record must contain any appropriate record separator or count characters. action This is a pointer to an integer.
4: Record Transfer Interface (BSCRTI) dtime This is a pointer to a descriptor. It is a character string containing the timeout value in the following time string format: VMS format: UNIX format: dak dddd hh:mm:ss hh:mm:ss This is a longword containing the DAK node indicator. If the indicator is 1, data acknowledgments are read from the DAK node; otherwise, they are read from the link’s read node. Return Codes See Table 5–2 on page 95 for full descriptions of the error return codes.
BSCTRAN Programmer’s Guide /* Use common rdblock for BSCWRIT and BSCREAD */ TRANBUF rdblock; /* rdblock for ICP responses */ . struct dsc$descriptor_s wr_recbuf; /* Write record buffer */ . /********************************************************************/ /* Call BSCASL to assign I/O channel. */ /* Open the SEND file and get one record at a time.
4: Record Transfer Interface (BSCRTI) 4.8 ICP Read Block The ICP Read Block is a data structure used by the BSC File Transfer program to receive data or control information from the ICP. It is also used for error handling based on the value of the error status byte of the ICP control header. The entire data structure is described by the following C typedef (refer to the BSCTRAN.
BSCTRAN Programmer’s Guide 92 DC 900-1406E
Chapter 5 Error Handling The BSC File Transfer program handles the following three categories of errors: • Errors returned by the various levels of the BSC File Transfer program. These are described in Section 5.1. • Errors returned by the ICP, described in Section 5.2. • Unexpected responses from the ICP, described in Section 5.3. Error return codes are defined in the BSCTRAN.INC include file. 5.
BSCTRAN Programmer’s Guide Table 5–1: Warnings Output by BSC File Transfer Program Warning Message Specified Area Link is stopped Link number (after a fatal error and abort) Link already started Link number Receiving carriage control /ESCAPE or /FORTRAN 94 Received empty file Filename File deleted Filename Partial file Filename Unexpected file Default filename DC 900-1406E
5: Error Handling Table 5–2: Error Return Codes Used by BSC File Transfer Program (defined in the BSCTRAN.
BSCTRAN Programmer’s Guide Table 5–2: Error Return Codes Used by BSC File Transfer Program (Cont’d) (defined in the BSCTRAN.
5: Error Handling 5.2 BSC ICP Errors Table 5–3 describes the possible errors returned from the ICP and how each is handled in SEND and RECEIVE modes. If the DEFAULT /ABORT option is set, then for all cases causing an abort of the BSC File Transfer program, the applicable link is stopped and an informational message is sent to the system output device advising the user to restart the link. If the DEFAULT /NOABORT option is set, the user is returned to the BSCTRAN command prompt.
BSCTRAN Programmer’s Guide Table 5–3: BSC ICP Error Return Codes (defined in the BSCTRAN.
5: Error Handling 5.3 Unexpected Responses from the ICP Unexpected responses from the ICP can be in the form of data, status, or control information due to previous or interfering activity on the line. They can also be caused by performing BSC File Transfer commands in an improper order such as executing a SEND or SET/STOP command when data has already been received from the remote site and is awaiting a RECEIVE command. Status information (for examples, configuration reports) will be ignored.
BSCTRAN Programmer’s Guide 100 DC 900-1406E
Chapter 6 Cautions The following is a list of cautions that users of the BSC File Transfer program should heed. • The default size is 1024 bytes for the BSCTRAN write buffer and the ICP message buffers, but the value can be increased up to 4096 by means of the DEFAULT /BUFSIZE=n command. The BSCTRAN write buffer size must always be less than or equal to the ICP message buffer size to avoid buffer errors from Freeway. Refer to Section 2.5 on page 33 for details of the DEFAULT /BUFSIZE command.
BSCTRAN Programmer’s Guide • When transmitting 3780 executable-image files between VMS or UNIX sites, use the commands SEND /TRANS /BINARY and RECEIVE /FIXED /BINARY. • When transmitting 3780 object-image files between VMS or UNIX sites, use the commands SEND /TRANS /BINARY and RECEIVE /BINARY. Be sure the transmission block size (configuration option 8) is larger than the largest record.
Chapter 7 Note Example BSCTRAN Usage In this document, the term “Freeway” can mean either a Freeway server or an embedded ICP. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface)). This chapter shows an example of how BSCTRAN is used. The BSCTRAN program requires that you use the supplied DLI and TSI configuration files which are named dlitrancfg and tsitrancfg respectively.
BSCTRAN Programmer’s Guide 7.1 DLI Configuration File Example Figure 7–1 is an example of a DLI configuration file that defines several sessions. //------------------------------------------------------------------// // DLI configuration file for BSCTRAN // // // // This file defines the connections between the BSCTRAN program // // and individual ICP ports on the Freeway server(s). In this // // file, a main section is defined along with a section for each // // ICP port.
7: Example BSCTRAN Usage //------------------------------------------------------------------// // Define 16 port names for Freeway 0, ICP board 0. // // The transport connection name "bsc0" is used for all ports on // // Freeway 0. In order to complete the connection you must replace // // the dummy server name "Freeway0" in the tsi configuration file // // with the name of your Freeway server.
BSCTRAN Programmer’s Guide FWY0B0L3 { Protocol = "RAW"; Transport = "bsc0"; BoardNo = 0; PortNo = 3; AsyncIO = "yes"; AlwaysQio = "yes"; Timeout = 0; // // // // // RAW session type // Transport connection name // defined in TSI configuration// ICP board number -- based 0 // Port number. // // Zero means never timeout // } . . . //------------------------------------------------------------------// // Define 16 port names for Freeway 1, ICP board 0.
7: Example BSCTRAN Usage 7.2 TSI Configuration File Example (Freeway Server Only) Figure 7–2 is an example of a TSI configuration file that defines two connections. The connections specify their Freeway servers to be freeway0 and freeway1, respectively. //----------------------------------------------------------------------------// // TSI configuration file for BSCTRAN // // // // This file defines TSI parameters for the BSCTRAN file transfer program.
BSCTRAN Programmer’s Guide //----------------------------------------------------------------------------// // bsc0: TCP socket interface connection for BSCTRAN on Freeway 0. // // // // Change the Freeway server name below to the name of your Freeway.
7: Example BSCTRAN Usage 7.3 Command Procedure Example The VMS DCL command procedure shown in Figure 7–3 demonstrates most of the commands and options of the BSCTRAN program. The command procedure uses DLI sessions FWY0B0L2 and FWY0B0L3. The connection is bsc0, and the Freeway server name is freeway0. The demonstration requires Freeway server freeway0, ICP 0, links 2 and 3 to be connected with a loopback cable.
BSCTRAN Programmer’s Guide $ ! Set up to catch fatal errors if BSCTRAN has to abort. $ ON ERROR THEN GOTO END $ ! Set to echo the BSCTRAN commands to SYS$OUTPUT. $ SET VERIFY=IMAGE $ RUN BSCTRAN HELP ! Display the Help menu (comments are allowed) ! ! You only have to specify the server name once. SET 2 fwy0 /PAR2=0 ! Set EXTERNAL clock for loopback SET 2 /START ! Start Link 2 SET 3 /PAR2=1 /START ! or can configure and start together ! SHOW 2 ! Show link configuration SHOW 3 ! SEND TXT.
7: Example BSCTRAN Usage SET 2 /STOP ! Disable to reconfigure link to send SET 3 /STOP ! transparent data ! SET 2 /PAR10=0/PAR19=0 ! Turn data translation and message SET 3 /PAR10=0/PAR19=0 ! blocking off for transparent data SET 2 /PAR8=514/START ! Change block size to transmit full 512 SET 3 /PAR8=514/START ! bytes (514 = 512 + STX + ETX) SEND OBJ.TEST 2 /TRANS /BINARY ! /BIN = don’t insert RS chars RECEIVE TEST_3780.
BSCTRAN Programmer’s Guide 112 DC 900-1406E
Index A Abort BSCTRAN 35, 40, 41, 45, 95, 97, 98 Audience 9 B Binary data 41, 45, 46 C Caution (BSCTRAN) binary data 42, 45 ICP message buffer 38 ICP transmission block 38 list 101 transparent data 42 unexpected response 78, 82, 89, 91 using /LOCKSTART option 32 write buffer 38 Commands autodial start 39 BSCDIAL procedure 55 BSCMODEM procedure 77 data transfer transparent 42 ICP message buffer size 37 link configuration 28, 31 BSCSET procedure 65 BSCSHOW procedure 67 modem configuration 39 BSCDIAL procedur
BSCTRAN Programmer’s Guide D DCL command procedure example 109 DLI configuration file example 104 Documents reference 11 Download ICP 28 card image 43 RJE 15 Interface batch (BSCTRAN) 17, 19 DLI (ICPDLI) 17 file transfer (BSCFTI) 17, 51 record transfer (BSCRTI) 17, 73 user (BSCTRAN) 17, 19 E Error codes BSCTRAN (table) 95 ICP (BSCTRAN) 98 Examples BSCTRAN 2780 records 36 HELP command 26 SET command 32 VMS operator console logging 34 BSCTRAN usage 103 DCL command procedure 109 DLI configuration file 104 pr
Index BSCWRIT 87 Product programs BSCTRAN 15 support 14 Q Queue VMS system batch 34 VMS system printer 34 R Record attributes 48 concatenation 42, 46 format 48 fixed length 46 length 45 padding 43, 46 separator 36, 41, 45 splitting 37, 41, 42, 43, 46 Reference documents 11 Responses data acknowledge 41 trace BSCTRACE procedure 85 unexpected (BSCTRAN) 51, 73, 78, 82, 89, 91, 95, 99 Revision history 13 U User 89 application 10, 51, 73 data structures 52, 66, 68, 91 V VMS command procedure 20 example 110 RMS
BSCTRAN Programmer’s Guide 116 DC 900-1406E
BSCTRAN Programmer’s Guide DC 900-1406E 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.
