Data Management Library TRANSFER Release D30 Documentation Supplement Abstract This document describes the D30 release of TRANSFER, which includes enhancements for gateways, improvements in some TMANAGER functions, and support for X.400 probes. Changes released in other IPMs and high PIN changes are also documented. Product Version TRANSFER D30 Supported Releases This manual supports D30.00 and all subsequent releases until otherwise indicated in a new edition.
Document History Edition Part Number Product Version Earliest Supported Release Published First 118474 TRANSFER D30 D30.00 July 1995 New editions incorporate any updates since the previous edition. A plus sign (+) after a release ID indicates that this manual describes function added to the base release, either by an interim product modification (IPM) or by a new product version on a .99 site update tape (SUT). Ordering Information For manual ordering information: domestic U.S.
Contents About This Manual v Notation Conventions vii 1.
1.
About This Manual 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 CD Read disc. You can either FAX or mail the card to us. The FAX number and mailing address are provided on the card. Also provided on the Reader Comment Card is an Internet mail address.
Your Comments Invited vi About This Manual 118474 —TRANSFER Release D30 Documentation Supplement
Notation Conventions General Syntax Notation The following list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name [ ] Brackets.
General Syntax Notation Notation Conventions An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char..." Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be entered as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.
Notation Conventions Notation for Messages !o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a corresponding input parameter specifying the maximum length of the output buffer in bytes. For example: error := FILE_GETINFO_ ( filenum , [ filename:maxlen ] ) ; !i !o:i Notation for Messages The following list summarizes the notation conventions for the presentation of displayed messages in this manual. Nonitalic text.
Notation for Management Programming Interfaces Notation Conventions % Percent Sign. A percent sign precedes a number that is not in decimal notation. The %þnotation precedes an octal number. The %Bþnotation precedes a binary number. The %Hþnotation precedes a hexadecimal number. For example: %005400 P=%p-register E=%e-register Notation for Management Programming Interfaces UPPERCASE LETTERS. Uppercase letters indicate names from definition files; enter these names exactly as shown.
1 TRANSFER D30 Documentation Supplement Introduction The D30 release of TRANSFER includes enhancements for gateways, improvements in some TMANAGER functions, and support for X.400 probes. Changes released in other IPMs and high PIN changes are also documented. Related Documents The following manuals contain more detailed information about the TRANSFER delivery system: • • • The TRANSFER Programming Guide is a guide to writing application programs that use the TRANSFER delivery system.
New Parameters • • • TRANSFER D30 Documentation Supplement The TMANAGER and ADMIN screens include node name, date, and time. The retention time for X400 Special Folders can be set to less than 14 days.
TRANSFER D30 Documentation Supplement Installation and Configuration TIMEINTERVAL TIMEMULTIPLE READYINTERVAL DELIVERYWORKPERTRANS ALTERX400FOLDERS ALTERINGSUFFIX COUNTMESSAGES ALLOWALLSUFFIXES (TSCHED) (TSCHED) (TSCHED) (TSCHED) (TISERV) (TISERV) (TISERV/TWORK/TRECV) (TISERV/TWORK/TRECV/TDBSERV) BLDTOITEMDATA (IMPORTER) if TRUE, causes the Importer to store bilaterally defined body parts in PCDATA items instead of external object files.
Functional Specifications ALTERINGSUFFIX TRANSFER D30 Documentation Supplement (TISERV) instructs TISERV to NOT cache session records in memory. If FALSE, then the most recently accessed session records are stored in memory for improved performance. If you use the ALTER-SESS-SUFFIX-UOW, it is set to TRUE. This parameter is optional. ALLOWALLSUFFIXES (TISERV/TWORK/TRECV/TDBSERV) instructs TISERV to NOT check the PROFILE record when adding a recipient to see if that recipient allows suffixes.
TRANSFER D30 Documentation Supplement ACK-RECEIPT-D30 03 Reserved-4 02 suffix-to-match END. PIC A VALUE "N". PIC X(120). DEF ack-receipt-D30-rsp. 02 hdr 03 self-ident 03 uow-code 02 retn-code 02 retn-code-detail 02 num-marked END. PIC AA VALUE "UW". TYPE BINARY 16 UNSIGNED VALUE 190. TYPE BINARY 16. TYPE BINARY 16. TYPE BINARY 16. HDR specifies the UOW header. The UOW-CODE value is 190. ITEM-ID specifies the item ID of the package header for the received package.
ACK-RECEIPT-D30 TRANSFER D30 Documentation Supplement SUPPRESS-CERT-ACK indicates to TISERV to return a certification acknowledgment when the ACKRECEIPT-D30-UOW is done for certified packages. Set this flag to “Y” to prevent the certified acknowledgment. SUPPRESS-RECEIPT-NOTIFY indicates to TISERV to return a receipt report when the ACK-RECEIPT-D30-UOW is done for recipients that need it. Set this flag to “Y” to prevent the receipt report from being sent.
TRANSFER D30 Documentation Supplement ALTER-SESS-SUFFIX ACK-RECEIPT-D30 Operation The ACK-RECEIPT-D30 UOW performs the same function as ACK-RECEIPT after a matching recipient record is found according to the RECIPIENT-INDICATOR and, optionally, the SUFFIX-TO-MATCH. Note. The suffix comparison is case sensitive. ACK-RECEIPT-D30 sets the EXAMINED flag in the recipient record in the package identified by ITEM-ID that was found depending on RECIPIENT-INDICATOR.
TRANSFER D30 Documentation Supplement Node and Time on TMANAGER and ADMIN Screens 02 retn-code 02 retn-code-detail 02 old-suffix END. TYPE BINARY 16. TYPE BINARY 16. PIC X(120). HDR specifies the UOW header. The UOW-CODE value is 133. NEW-SUFFIX specifies the suffix to place in the session record for this session. The session ID is obtained from the IPC-HDR. The NEW-SUFFIX can be all spaces to remove any suffix that was in use. If a correspondent name is supplied before the suffix, it is ignored.
TRANSFER D30 Documentation Supplement Unhold Ready Task is also an option on ADMIN screens. All screens include the node name just right of the screen title. The word “SCREEN” is removed from each screen in order to make room for the node name. The default for ADMIN is not to display the node names on the screens. To display node names, change the INITIAL attribute of the program ADMIN from ASCII-ADMIN to ASCII-ADMIN-NODE.
Improved TMANAGER HELD Reads TRANSFER D30 Documentation Supplement Improved TMANAGER HELD Reads The reading of HELD records required a read through the entire ready file, which made it difficult to check for held records on a system with a large backlog of tasks to perform. When a message is held, its priority is also altered to move it to the bottom of the queue. SMSERV now uses the new priority (bit 0 = 1) to keyposition into the READY file.
TRANSFER D30 Documentation Supplement X400 Gateway Message Priority Item ID Session Record Caching The SESSION file is one of the most heavily read files of the TRANSFER delivery system. Analysis shows that messages from a given client are frequently sent to the same TISERV process. If the session record is kept in memory, the read of the SESSION file is avoided, resulting in a significant performance improvement. The TISERV keeps a cache of the most recently accessed session records.
X.400 Probes TRANSFER D30 Documentation Supplement To allow adjustment of the priority of the incoming message, three new parameters are added to the X400-IMPORTER server class: PARAM PRIORITYURGENT PARAM PRIORITYNORMAL PARAM PRIORITYLOW (Default 125) (Default 75) (Default 25) PRIORITYURGENT must be greater than PRIORITYNORMAL, and PRIORITYNORMAL must be greater than PRIORITYLOW. It must also be less than or equal to the maximum priority set in the _X400_ depot's profile, which defaults to 150.
TRANSFER D30 Documentation Supplement X.400 Probes 2. Use ALTER-ITEM-DESCR and set the PROBE-MSG field of the DELIVCONTROL-FLAGS to “Y.” 3. Add at least one X400 Recipient, using ADD-X400-RECIP. If you want notification that the probe was successful, set the DELIV-NOTIFY field in OPTIONS to “Y.” Otherwise, you are only notified if the probe was unsuccessful. You may add as many X400 recipients to the probe as desired.
X.400 Probes TRANSFER D30 Documentation Supplement This is not as a serious a problem as are Replies and reports on non-probes. See “Considerations” later in this section for more information. Incoming Probes After the TRANSFER Gateway detects that the incoming message is a probe, it checks the existence of each O/R Name for which it is responsible. The Gateway checks to see if there is an XDIR server configured.
TRANSFER D30 Documentation Supplement Introduction to D30 TRANSFER Of more importance are STATUS packages created by the X400 Gateway when converting Delivery and Non-Delivery reports returned as the result of a TRANSFER probe. These reports can contain more than one reported-on recipient. STATUS Packages created by TRANSFER contain only one REPORTED-ON RECIP. TRANSFER Clients, therefore, cannot display more than one REPORTED-ON RECIP when displaying a STATUS package.
File Formats • TRANSFER D30 Documentation Supplement DEQ-D30, ENQ-D30, READQ-D30, ENQ-TIMED-D30 UOWs. TRANSFER is converted for use in D20 in the following way: • • • • All calls to superseded Guardian PROCs have been converted. New type system messages from $RECEIVE will be handled. All external interfaces that now use CPU-PIN will be converted to use process handle. Certain processes will be forced to run at low PINs to avoid problems with down-rev nodes.
TRANSFER D30 Documentation Supplement DEQ-D30 UOW are allowed only when the queue file is in the new format. If the format of the queue file and the UOW is not compatible, a new error code E-INCOMPATIBLE-QFILE (6007) is returned. DEF Queue-File-Def. 05 05 Partition-Key PIC X(2). Entry-Type PIC S9(4) COMP. 88 Visible-Entry VALUE 0. 88 Pending-Entry VALUE 1. 05 Effective-Time PIC X(8). 88 Effective-Now VALUE LOW-VALUES. 05 Queue-Name TYPE *. 05 Priority PIC 9(4) COMP. 05 Time-Of-Enq PIC X(8). 05 Cpu-Pin.
ENQ-D30 UOW 05 END TRANSFER D30 Documentation Supplement FILLER PIC X(1) VALUE LOW-VALUE. DEF Deq-D30-Rsp. 05 Hdr TYPE Uow-Hdr. 05 Retn-Code TYPE Uow-Retn-Code. *^ OK *^ E-BAD-TRANSACTION *^ E-MUST-BE-YN *^ E-RESERVED-MUST-BE-N *^ E-INVALID-PRIORITY *^ E-INVALID-MAX-DATASIZE *^ W-QUEUE-EMPTY *^ E-ERR-QUEUE-FILE *^ E-IO-TIMEOUT *^ W-DATA-TRUNCATED *^ E-INCOMPATIBLE-QFILE 05 Retn-Code-Detail TYPE Uow-Retn-Code-Detail. 05 05 05 05 05 Queue-Name TYPE *. Priority TYPE *. Time-Of-Enq PIC X(8).
TRANSFER D30 Documentation Supplement 05 05 05 * * * * END Queue-Name Priority Data-Byte-Count READQ-D30 UOW TYPE * VALUE SPACES. TYPE * VALUE 0. TYPE Max-Data-Size VALUE 0. Applications should define the actual format of the data portion. DEF Enq-D30-Rsp. 05 Hdr TYPE Uow-Hdr. 05 Retn-Code TYPE Uow-Retn-Code.
ENQ-TIMED-D30 UOW 05 END FILLER TRANSFER D30 Documentation Supplement PIC DEF Readq-D30-Rsp. 05 Hdr TYPE 05 Retn-Code TYPE *^ OK *^ W-EOF *^ E-MUST-BE-YN *^ E-RESERVED-MUST-BE-N *^ E-INVALID-PRIORITY *^ E-INVALID-MAX-DATASIZE *^ W-DATA-TRUNCATED *^ E-ERR-QUEUE-FILE *^ E-IO-TIMEOUT *^ E-INCOMPATIBLE-QFILE 05 Retn-Code-Detail TYPE 05 Queue-Name TYPE 05 Priority TYPE 05 Time-Of-Enq PIC 05 PHandle PIC 05 Data-Len TYPE * * Applications should define * portion. END X(1) VALUE LOW-VALUE. Uow-Hdr.
TRANSFER D30 Documentation Supplement Message Counting * END DEF Enq-Timed-D30-Rsp. 05 Hdr TYPE 05 Retn-Code TYPE *^ OK *^ E-BAD-TRANSACTION *^ E-MUST-BE-YN *^ E-RESERVED-MUST-BE-N *^ E-INVALID-PRIORITY *^ E-DATA-TOO-LONG *^ E-PAST-DATE-TIME *^ E-UNITS-MUST-BE-DHM *^ E-INVALID-DATE-TIME *^ E-INVALID-REL-TIME-QTY *^ E-ERR-QUEUE-FILE *^ E-IO-TIMEOUT *^ E-WAITMANAGER-UNAVAIL *^ E-INCOMPATIBLE-QFILE 05 Retn-Code-Detail TYPE 05 Time-Of-Enq PIC 05 PHandle PIC END Uow-Hdr. Uow-Retn-Code. Uow-Retn-Code-Detail.
Message Counting * Class TRANSFER D30 Documentation Supplement Rec-seq-num 1 = 1st, 2 = 2nd and 3 = 3rd 10 10 10 10 Reset-timestamp Last-Update-timestamp Total-Message-count Node 15 Message-count 10 FILLER TYPE BINARY 64. TYPE BINARY 64. TYPE BINARY 32. OCCURS 256 TIMES. TYPE BINARY 32. PIC X(28). PROFILE Types: 951 952 953 954 - Local submits Local deliveries Sent remote Received from remote Considerations The rec-seq-num indicates class. Rec-seq-num 1 = 1st, 2 = 2nd, and so on.
TRANSFER D30 Documentation Supplement X400 Folder Retention Considerations It is intended that a customer-written program is used to extract the count information and to reset the counters. By using the READ-PROFILE-REC and WRITE-PROFILEREC UOWs, you can do this easily. See “GETCNT Example” for a code fragment indicating how to do this. You cannot count messages dynamically and turned it off and on as desired without taking the system down.
Export/Import of Binary Objects • TRANSFER D30 Documentation Supplement When the retention time for the folder is reached (currently two weeks), the item is deleted and the mapping entries are deleted. If there is a problem with delivering the message, the X400 system returns a NonDelivery report: • • • • The Importer builds a TRANSFER STATUS package (a report).
TRANSFER D30 Documentation Supplement • • Bilaterally-Defined Body Parts Use non-mail type packages. With this form, the contents of the P1 is a single octet string without any X.400-defined structure. The interpretation of the data is determined by the application. Use bilaterally-defined body parts. This method also consists of data that must be interpreted by the application, but this data is within a body part so that it can be included in the P2 of a message with other body parts.
GETCNT Example TRANSFER D30 Documentation Supplement GETCNT Example The following is an example of GETCNT used to extract count information.
TRANSFER D30 Documentation Supplement GETCNT Example %d", @error , @rt, @rn ); END; END; ! reset^counter^rec SUBPROC add^MCI^info; BEGIN ! Customize and write out information to file END; ! add^MCI^info ! Get the submit counts rec^type := 951; FOR rec^seq^num := 1 TO 3 DO BEGIN ! MCI^submit^count^info overlays MCI^Message^count^info ! but is shorter.
GETCNT Example TRANSFER D30 Documentation Supplement IF reset^counters THEN CALL reset^counter^rec ( rec^type , rec^seq^num ); END; END; ! for loop on class print ( " " ); ! Get the delivery counts rec^type := 952; FOR rec^seq^num := 1 TO 3 DO BEGIN IF ( error := read^profile^rec ( rec^type , rec^seq^num , MCI^message^count^info, $LEN ( MCI^message^count^info ) , skip^exact, depot^flag , data^len ) ) THEN BEGIN IF error = -4001 THEN ! not there BEGIN print ( "No delivery^count record for class %d" , @rec^
TRANSFER D30 Documentation Supplement GETCNT Example print ( " " ); ! Get the Twork counts rec^type := 953; FOR rec^seq^num := 1 TO 3 DO BEGIN IF ( error := read^profile^rec ( rec^type , rec^seq^num , MCI^message^count^info, $LEN ( MCI^message^count^info ) , skip^exact, depot^flag , data^len ) ) THEN BEGIN IF error = -4001 THEN ! not there BEGIN print ("No Send^count record for class %d", @rec^seq^num ); END ELSE BEGIN eprint ( "** Error %d trying to read Send^count record for class %d", @rec^seq^num ); E
GETCNT Example TRANSFER D30 Documentation Supplement IF ( error := read^profile^rec ( rec^type , rec^seq^num , MCI^message^count^info, $LEN ( MCI^message^count^info ) , skip^exact, depot^flag , data^len ) ) THEN BEGIN IF error = -4001 THEN ! not there BEGIN print ("No Receive^count record for class %d" , @rec^seq^num ); END ELSE BEGIN eprint ("** Error %d trying to read Receive^count record for class %d", @rec^seq^num ); END; END ELSE ! got a record, list results BEGIN have^counts := true; fts1 := MCI^mes
