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.
Part Number
Edition
Published
Release ID
118474
First
July 1995
D30.02
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. customers, call 1-800-243-6886; international customers, contact
your local sales representative.
Document Disclaimer
Information contained in a manual is subject to change without notice. Please check with your authorized Tandem
representative to make sure you have the most recent information.
Export Statement
Export of the information contained in this manual may require authorization from the U.S. Department of
Commerce.
Examples
Examples and sample programs are for illustration only and may not be suited for your particular purpose. Tandem
does not warrant, guarantee, or make any representations regarding the use or the results of the use of any examples
or sample programs in any documentation. You should verify the applicability of any example or sample program
before placing the software into productive use.
U.S. Government Customers
FOR U.S. GOVERNMENT CUSTOMERS REGARDING THIS DOCUMENTATION AND THE ASSOCIATED
SOFTWARE:
These notices shall be marked on any reproduction of this data, in whole or in part.
NOTICE: Notwithstanding any other lease or license that may pertain to, or accompany the delivery of, this
computer software, the rights of the Government regarding its use, reproduction and disclosure are as set forth in
Section 52.227-19 of the FARS Computer Software—Restricted Rights clause.
RESTRICTED RIGHTS NOTICE: Use, duplication, or disclosure by the Government is subject to the
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 52.227-7013.
RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions
as set forth in paragraphþ(b)(3)(B) of the rights in Technical Data and Computer Software clause in
DAR 7-104.9(a). This computer software is submitted with “restricted rights.” Use, duplication or disclosure is
subject to the restrictions as set forth in NASA FARþSUP 18-52þ227-79 (Aprilþ1985) “Commercial Computer
Software—Restricted Rights (Aprilþ1985).” If the contract contains the Clause at 18-52þ227-74 “Rights in Data
General” then the “Alternate III” clause applies.
U.S. Government Users Restricted Rights — Use, duplication or disclosure restricted by GSA ADP Schedule
Contract.
Unpublished — All rights reserved under the Copyright Laws of the United States.
Contents
About This Manual v
Notation Conventions vii
1. TRANSFER D30 Documentation Supplement
Introduction 1-1
Related Documents 1-1
Assumptions 1-1
Enhancements 1-1
New Parameters 1-2
Installation and Configuration 1-2
Functional Specifications 1-4
ACK-RECEIPT-D30 1-4
ALTER-SESS-SUFFIX 1-7
Node and Time on TMANAGER and ADMIN Screens 1-8
Unhold Ready Task 1-9
Improved TMANAGER HELD Reads 1-10
TSAMPLE Priority 0 Counting 1-10
External Object Transport Enhancements 1-10
Text Server Utilization Improvement 1-10
Item ID Session Record Caching 1-11
X400 Gateway Message Priority 1-11
X.400 Probes 1-12
Altering X400 Gateway Folder Retention Times 1-15
Introduction to D30 TRANSFER 1-15
File Formats 1-16
DEQ-D30 UOW 1-17
ENQ-D30 UOW 1-18
READQ-D30 UOW 1-19
ENQ-TIMED-D30 UOW 1-20
Message Counting 1-21
X400 Folder Retention Considerations 1-23
Export/Import of Binary Objects 1-24
Bilaterally-Defined Body Parts 1-25
GETCNT Example 1-26
TRANSFER Release D30 Documentation Supplement— 118474
iii
1. TRANSFER D30 Documentation Supplement
iv
Contents
118474 —TRANSFER Release D30 Documentation Supplement
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. When you
send an Internet mail message to us, we immediately acknowledge receipt of your
message. A detailed response to your message is sent as soon as possible. Be sure to
include your name, company name, address, and phone number in your message. If
your comments are specific to a particular manual, also include the part number and title
of the manual.
Many of the improvements you see in Tandem manuals are a result of suggestions from
our customers. Please take this opportunity to help us improve future manuals.
TRANSFER Release D30 Documentation Supplement— 118474
v
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. Brackets enclose optional syntax items. For example:
TERM [\system-name.]$terminal-name
INT[ERRUPTS]
A group of items enclosed in brackets is a list from which you can choose one item or
none. The items in the list may be arranged either vertically, with aligned brackets on
each side of the list, or horizontally, enclosed in a pair of brackets and separated by
vertical lines. For example:
LIGHTS [ ON
]
[ OFF
]
[ SMOOTH [ num ] ]
K [ X | D ] address-1
{ } Braces. A group of items enclosed in braces is a list from which you are required to
choose one item. The items in the list may be arranged either vertically, with aligned
braces on each side of the list, or horizontally, enclosed in a pair of braces and separated
by vertical lines. For example:
LISTOPENS PROCESS { $appl-mgr-name }
{ $process-name }
ALLOWSU { ON | OFF }
| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
INSPECT { OFF | ON | SAVEABEND }
… Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you
can repeat the enclosed sequence of syntax items any number of times. For example:
M address-1 [ , new-value ]...
[ - ] {0|1|2|3|4|5|6|7|8|9}...
TRANSFER Release D30 Documentation Supplement— 118474
vii
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.#su-name
Quotation marks around a symbol such as a bracket or brace indicate the symbol is a
required character that you must enter as shown. For example:
"[" repetition-constant-list "]"
Item Spacing. Spaces shown between items are required unless one of the items is a
punctuation symbol such as a parenthesis or a comma. For example:
CALL STEPMOM ( process-id ) ;
If there is no space between two items, spaces are not permitted. In the following
example, there are no spaces permitted between the period and any other items:
$process-name.#su-name
Line Spacing. If the syntax of a command is too long to fit on a single line, each continuation
line is indented three spaces and is separated from the preceding line by a blank line.
This spacing distinguishes items in a continuation line from items in a vertical list of
selections. For example:
ALTER [ / OUT file-spec / ] CONTROLLER
[ , attribute-spec ]...
!i and !o. In procedure calls, the !i notation follows an input parameter (one that passes data
to the called procedure); the !o notation follows an output parameter (one that returns
data to the calling program). For example:
CALL CHECKRESIZESEGMENT (
segment-id
, error
) ;
!i
!o
!i,o. In procedure calls, the !i,o notation follows an input/output parameter (one that both
passes data to the called procedure and returns data to the calling program). For
example:
error := COMPRESSEDIT ( filenum ) ;
!i,o
!i:i. In procedure calls, the !i:i notation follows an input string parameter that has a
corresponding parameter specifying the length of the string in bytes. For example:
error := FILENAME_COMPARE_ (
viii
filename1:length
, filename2:length ) ;
!i:i
!i:i
118474 —TRANSFER Release D30 Documentation Supplement
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. Nonitalic letters, numbers, and punctuation indicate text that is displayed or
returned exactly as shown. For example:
Backup Up.
lowercase italic letters. Lowercase italic letters indicate variable items whose values are
displayed or returned. For example:
p-register
process-name
[ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For
example:
Event number = number [ Subject = first-subject-value ]
A group of items enclosed in brackets is a list of all possible items that can be displayed,
of which one or none might actually be displayed. The items in the list might be
arranged either vertically, with aligned brackets on each side of the list, or horizontally,
enclosed in a pair of brackets and separated by vertical lines. For example:
LDEV ldev [ CU %ccu | CU %... ] UP [ (cpu,chan,%ctlr,%unit) ]
{ } Braces. A group of items enclosed in braces is a list of all possible items that can be
displayed, of which one is actually displayed. The items in the list might be arranged
either vertically, with aligned braces on each side of the list, or horizontally, enclosed in
a pair of braces and separated by vertical lines. For example:
LBU { X | Y } POWER FAIL
process-name State changed from old-objstate to objstate
{ Operator Request. }
{ Unknown.
}
| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
Transfer status: { OK | Failed }
TRANSFER Release D30 Documentation Supplement— 118474
ix
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. For example:
ZCOM-TKN-SUBJ-SERV
lowercase letters. Words in lowercase letters are words that are part of the notation, including
Data Definition Language (DDL) keywords. For example:
token-type
!r.
The !r notation following a token or field name indicates that the token or field is
required. For example:
ZCOM-TKN-OBJNAME
!o.
token-type ZSPI-TYP-STRING.
!r
The !o notation following a token or field name indicates that the token or field is
optional. For example:
ZSPI-TKN-MANAGER
token-type ZSPI-TYP-FNAME32.
!o
Change Bar Notation
Change bars are used to indicate substantive differences between this edition of the
manual and the preceding edition. Change bars are vertical rules placed in the right
margin of changed portions of text, figures, tables, examples, and so on. Change bars
highlight new or revised information. For example:
The message types specified in the REPORT clause are different in the COBOL85
environment and the Common Run-Time Environment (CRE).
The CRE has many new message types and some new message type codes for old
message types. In the CRE, the message type SYSTEM includes all messages
except LOGICAL-CLOSE and LOGICAL-OPEN.
x
118474 —TRANSFER Release D30 Documentation Supplement
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.
The TRANSFER Reference Manual provides reference material for application
programmers who write programs that use the features of the TRANSFER delivery
system. It also lists the text and meaning of all messages returned to TRANSFER
application programs.
The TRANSFER Administration Guide lists the text and meaning of all messages
returned to TRANSFER application programs.
Assumptions
This document is intended for application programmers familiar with the TRANSFER
delivery system.
Enhancements
The following enhancements are included in this release:
•
•
•
•
•
•
•
The ACK^RECEIPT UOW allows selective RECIP records to be acknowledged.
The ALTER-SESS-SUFFIX changes only the suffix in the session record, which
allows the CREATE-ITEM UOW to pick up the correct suffix.
A held Ready Task can be unheld.
The TMANAGER read of held records is improved.
The priority of Imported X400 messages can be set by using PARAMs.
A parameter for TSAMPLE to only count non-priority zero records during specified
periods is included.
X.400 probes are supported.
TRANSFER Release D30 Documentation Supplement— 118474
1- 1
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.
The TRANSFER program can run high PIN processes and accept high PIN
requestors,
New Parameters
The following new parameters are included in this release:
Wait Manager
NUMTOWAKE min = 1,
default = all
TSCHED
TIMEINTERVAL min = 60, default = 60
READYINTERVAL min = 60, default = 60
TIMEMULTIPLE Max = 100, min = 1, default = 1
DELIVERYWORKPERTRANS Max = 20, min = 1, default = 10
TISERV
ALTERX400FOLDERS FALSE (default), TRUE
ALTERINGSUFFIX TRUE (default), FALSE
TISERV, TWORK and TRECV
COUNTMESSAGES NONE (default), Messages, Delivery, Both
ALLOWALLSUFFIXES FALSE (default), TRUE
TDBSERV
ALLOWALLSUFFIXES FALSE (default), TRUE
X400 Importer
PRIORITYLOW Default = 25
PRIORITYNORMAL Default = 75
PRIORITYURGENT Default = 125
BLDTOITEMDATA FALSE (default), TRUE
X400 Exporter
MAXPRILOW Default = 74
(No max/min)
MAXPRINORMAL Default = 124 (No max/min)
Installation and Configuration
A new parameter has been added to TRDEFLTS (DEFINETR) called TRSETHIGHPIN.
If set to YES, the TRANSFER servers that can run as high PIN processes are configured
to do so.
The following parameters are recognized but cannot be accessed directly by using
CDTRDEF. You must include them in CUSTCNFG.
BLDTOITEMDATA
NUMTOWAKE
1- 2
(IMPORTER)
(WMSERV)
118474 —TRANSFER Release D30 Documentation Supplement
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. The Exporter puts both external object files
and PCDATA items into bilaterally-defined body parts. For more information, see
the section on Export/Import of Binary Objects.
NUMTOWAKE
(WMSERV)
specifies how many waiters to awaken whenever an ENQ is detected. The default is
all, the minimum is 1. This parameter is optional.
TIMEINTERVAL
(TSCHED)
specifies how many seconds occur between each check of the TIME file. The units
are seconds. The default is 60. This parameter is optional.
TIMEMULTIPLE
(TSCHED)
specifies how many records can be moved from TIME to READY each
TIMEINTERVAL seconds. The default is 1, and the maximum is 100. This
parameter is optional.
READYINTERVAL
(TSCHED)
determines how long the TSCHED waits before repositioning to the beginning of the
READY file to determine if any higher priority tasks have been added. The default is
60, which is also the minimum. The units are seconds. This parameter is optional.
DELIVERYWORKPERTRANS
(TSCHED)
determines how much delivery work a TAREQ does before starting a new TMF
transaction. If you encounter frequent locks on scans of the INBOX, this parameter
can be reduced to shorten the active time of the transaction. The default is 10, the
maximum is 20, and the minimum is 1. The units are weighted values used within
TAREQ to calculate how long a TMF transaction is active. TAREQ attempts to
calculate the “cost” of agent processing and to reduce long transactions. This
parameter is optional.
ALTERX400FOLDERS
(TISERV)
instructs TISERV to allow the retention time for the X400 special folders to be less
than 14 days. This parameter is optional.
TRANSFER Release D30 Documentation Supplement— 118474
1- 3
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. This is a performance improving parameter if
suffixes are used extensively. This parameter is optional.
COUNTMESSAGES
(TISERV/TWORK/TRECV)
instructs TISERV processes to gather delivery statistics about messages. This
parameter is optional. The four possible values for COUNTMESSAGES reunion
are:
NONE
The default. No message counting is done
MESSAGES
Counts only message creations
DELIVERY
Counts only the number of recipients
BOTH
Counts both message creations and the number of recipients
Functional Specifications
The following sub-section describes the functional specifications for this release.
ACK-RECEIPT-D30
ACK-RECEIPT-D30 acknowledges the receipt of a package, an operation recommended
whenever a client retrieves a package. Many clients only acknowledge receipt if the
package is retrieved from the INBOX folder. This UOW is an extension of the function
provided in the basic ACK-RECEIPT. ACK-RECEIPT-D30 allows the client or agent
program to specify which recipient records are to be marked examined.
DEF ack-receipt-D30-uow.
02 hdr
03 self-ident
PIC AA VALUE "UW".
03 uow-code
TYPE BINARY 16 UNSIGNED VALUE 190.
02 item-id.
03 dummy PIC X(12).
02 recipient-indicator
PIC AA.
88 exact-match-with-logon VALUE "EL".
88 first-recip-found
VALUE "FR".
88 all-suffixes
VALUE "AS".
88 specific-suffix
VALUE "SS".
02 notification-suppress-flags.
03 suppress-cert-ack
PIC A VALUE "N".
03 suppress-receipt-notify
PIC A VALUE "N".
03 Reserved-3
PIC A VALUE "N".
1- 4
118474 —TRANSFER Release D30 Documentation Supplement
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.
RECIPIENT-INDICATOR
indicates to TISERV which of the several options to use in locating and marking
recipient records as examined. The correspondent name TISERV searches for is
always the current correspondent, the name given in the START-SESSION-UOW.
EXACT-MATCH-WITH-LOGON
VALUE "EL"
indicates to TISERV to search for a recipient record that exactly matches the
correspondent name and suffix used in the START-SESSION-UOW.
FIRST-RECIP-FOUND VALUE "FR"
indicates to TISERV to search for the first recipient record that matches the
correspondent name used in the START-SESSION-UOW. Any suffix in the recipient
record or the START-SESSION-UOW is NOT used to locate the record to mark.
ALL-SUFFIXES VALUE "AS"
indicates to TISERV to mark as examined any recipient record that has a matching
correspondent name. All suffixes are ignored. This option is used primarily by
gateway programs.
SPECIFIC-SUFFIX VALUE "SS"
indicates to TISERV to search for a recipient record that has a suffix that matches
the one given in SUFFIX-TO-MATCH. Only the matching record will be marked.
NOTIFICATION-SUPPRESS-FLAGS
suppresses the delivery of certification and receipt acknowledgments. It is expected
that the acknowledgments are done by some other application.
TRANSFER Release D30 Documentation Supplement— 118474
1- 5
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.
SUFFIX-TO-MATCH
specifies the suffix to look for if RECIPIENT-INDICATOR equals SPECIFICSUFFIX. It must include the correspondent name and the parentheses in the same
format as START-SESSION-UOW or ALL-RECIP-UOW. The suffix comparison is
case- sensitive.
RETN-CODE
specifies the return code. TISERV returns a code in this field to indicate one of the
following entries:
0
4010
4035
4042
-4045
4045
4051
4080
4084
4094
4095
4178
OK
E-BAD-TRANSACTION
E-ITEM-NOT-FOUND
E-ITEM-NOT-PKG-HDR
W-TSCHED-UNAVAIL
E-TSCHED-UNAVAIL
E-MUST-BE-YN
E-PKG-NOT-RECEIVED
E-PKG-NOT-SUBMITTED
E-PKG-CANCELED
E-PKG-EXPIRED
E-INVALID-RECIP-INDICATOR
Request operation successful
No recipient records matched
A new error code
To indicate problems with the depot storage statistics facility:
4944
6114
6126
6127
E-ERR-DEPSTAT-FILE
E-DSF-INTERNAL-ERROR
E-DSF-STAT-ARRAY
E-DSF-BAD-TIMESTAMP
RETN-CODE-DETAIL
specifies an error number returned by a subsystem other than the TRANSFER
delivery system or is a further qualification of an error detected by the TRANSFER
delivery system.
NUM-MARKED
specifies the number of recipient records marked as examined.
1- 6
118474 —TRANSFER Release D30 Documentation Supplement
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. This
strategy has the following effect:
•
•
If the package is flagged by the sender for certification and the ACK-RECEIPT-D30
UOW is issued against the package for the first time by this recipient, the
TRANSFER delivery system transmits an acknowledgment package to the sender.
Acknowledgment is transmitted also if the sender requested receipt notification for
this recipient (unless the corresponding flag is set to “Y” to suppress this).
When the expiration date is reached, the TRANSFER delivery system checks the
EXAMINED flag. If this flag is set, the TRANSFER delivery system performs no
action. If this flag is not set and the DONT-REMOVE-ON-EXPIRE flag is not set,
the TRANSFER delivery system removes the package from the INBOX if the
package is still there and notifies the sender that the package was not examined by
the recipient.
It is not necessary to call ACK-RECEIPT-D30 from within a TMF transaction. ACKRECEIPT-D30 automatically starts and ends a transaction if one is required to perform
the request and no transaction ID is present.
The TRANSFER delivery system automatically marks a package delivered to a group's
INBOX folder as having been examined. This strategy prevents the generation of
messages pertaining to the expiration of the package.
See ACK-RECEIPT for depot storage statistics facility information pertaining to ACKRECEIPT-D30.
ALTER-SESS-SUFFIX
ALTER-SESS-SUFFIX changes the suffix stored in the session record. Any item created
after this UOW uses the new suffix for the sender portion of the Item descriptor record.
This UOW provides a way for gateway programs to more easily process incoming
messages.
DEF alter-sess-suffix-uow.
02 hdr
03 self-ident
03 uow-code
02 new-suffix
END.
DEF alter-sess-suffix-rsp.
02 hdr
03 self-ident
03 uow-code
PIC AA VALUE "UW".
TYPE BINARY 16 UNSIGNED VALUE 133.
PIC X(120).
PIC AA VALUE "UW".
TYPE BINARY 16 UNSIGNED VALUE 133.
TRANSFER Release D30 Documentation Supplement— 118474
1- 7
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.
If the suffix is not blank, it must begin with “(” and end with “)”. Within the
parentheses, the suffix can contain any characters EXCEPT commas, single and
double quotes, and left and right parentheses. If the suffix is blank, any existing
suffix is erased from the session record.
RETN-CODE
specifies the return code. TISERV returns a code in this field to indicate one of the
following entries:
0
4010
5624
OK
E-BAD-TRANSACTION
E-CORR-BAD-SUFFIX
RETN-CODE-DETAIL
specifies the error number returned by a subsystem other than the TRANSFER
delivery system or is a further qualification of an error detected by the TRANSFER
delivery system.
OLD-SUFFIX
specifies the suffix that was in the Session record prior to this UOW being
processed. It will be all spaces if there was no suffix.
The ALTER-SESS-SUFFIX UOW affects the operation of the ACK-RECEIPT UOW, as
the full name and suffix is used for normal processing.
The suffix stored in the session record is normalized, (converted to uppercase), multiple
blanks are compressed to a single blank, and any blanks immediately following the
“(”and immediately preceding the “)” are removed. The suffix is always separated from
the correspondent name by a single blank.
Node and Time on TMANAGER and ADMIN Screens
To avoid confusion when managing multiple TRANSFER nodes and to provide clear
information when printing, the node name is included on all TMANAGER screens. This
1- 8
118474 —TRANSFER Release D30 Documentation Supplement
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.
The TMANAGER Scheduler Queue Scan screen displays the date and time to the right
of the Item ID field. Each time data from a queue is read, the date and time field are
updated.
TMANAGER SCHEDULER QUEUE SCAN \SVLDEV
Page
1
END
READY
TIME
NET
Item Id:
14:28
Current Queue: READY
HELD
Scanned: 94-08-15
Creator
Pri
When
Type of
Inserted
Work
Node
Name
Held
(This screen has been modified to fit on a printed page.)
Unhold Ready Task
A new function added to the TMANAGER Scheduler Queue Scan Screen allows a task
to be unheld so it can be retried prior to CHECKSESSIONHOUR. The UNHOLD
function allows any one marked task to be unheld. The task priority is not different, so it
cannot be retried immediately.
TMANAGER SCHEDULER QUEUE SCAN \SVLDEV Page
1
READY
TIME
NET
HELD
Item Id:
Scanned: 94-8-15
Current Queue: READY
When
Type of
Node
Creator
Pri
Inserted
Work
Name
WICKHAM_DONALD
WICKHAM_DONALD
100
0
11-01 14:33
08-14 22:01
SF4=1st Page F10=Scan Queue
F9=Print
F12=Item Trace
1
8
END
14:28
Held
Y
Y
SF14=Recover
F16=Return
F14=UnHold F15=Help
SF16=Main Menu
(This screen has been modified to fit on a printed page.)
An internal UOW is sent to SMSERV to have it remove the held bit from the task and
update the READY file. The task is then processed according to normal READY file
handling.
The F14 function key is disabled for TIME and NET, and F14=UnHold is not shown
when the TIME or NET queue entries are displayed.
TRANSFER Release D30 Documentation Supplement— 118474
1- 9
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.
TSAMPLE Priority 0 Counting
Two new parameters are available in TSAMPLE to indicate that only non-priority 0
tasks are counted during peak usage. These parameters allow samples to be taken of
high priority work without having to read all the priority 0 records.
PEAKSTARTHOUR hour
Where hour indicates that any sample taken after this hour but before
PEAKENDHOUR does not count priority 0 tasks.
PEAKENDHOUR hour
Where hour ends peak time. Samples taken after this hour but before
PEAKSTARTHOUR count all records.
An asterisk (*) is used to mark samples that do not include priority 0 records.
External Object Transport Enhancements
The transport mechanism of external objects has been made more robust. Previously, if
the item descriptor on the receiving end was found, the assumption was that the file
existed and transport could possibly fail later. This area of code was examined and made
more resistant to external problems.
•
•
•
TWORK reports the file name and operating system error with any 4119 error.
TRECV reports the parent ID, object ID and file name for any 4118 error.
TRECV checks, at get-extobj-time, if the file is there. If not, it tells TWORK to
duplicate the file again.
Text Server Utilization Improvement
Servers rely on the Text Server to initialize their context's language and character set.
Initialization is required when an incoming request requires a context with a different
language or character set from the previous request but is not required if these are the
same. The check for matching language and character sets is improved.
The Text Server received more requests than necessary; these calls have been eliminated.
The Text Server normally consists of a single process, which can be a bottleneck on a
large system without this improvement.
1- 10
118474 —TRANSFER Release D30 Documentation Supplement
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. If the client uses the ALTER-SESSSUFFIX UOW, this caching must be turned off. A new PARAM, ALTERINGSUFFIX,
turns off caching of the session record. To instruct TISERV to do the caching, include
PARAM ALTERINGSUFFIX FALSE.
Typically, a client that does a SCAN-FOLDER UOW accesses one or more of the items
identified by the SCAN-FOLDER RSP. When the item is accessed, TISERV needs to
check to see if the user has access to the data records (or item descriptor). This check is
not necessary if the context of the SCAN-FOLDER RSP is retained.
An item ID cache is maintained, on a per-session basis, for the most recently accessed
session-id and the most recent items for that session. This cache reduces reads of the
IFOLDER and ITEMDESC file.
This item access checking is significant; the data records are blocked, so a high
percentage of the I/O on an item is security checking. In a simple test for retrieving 5
text records, the following I/Os were done:
•
•
•
•
One read to retrieve the session record, some of which can be avoided by caching
session records
One read from the IFOLDER file to determine item access security; this I/O is not
done if item ID is found in cache.
One read to retrieve the item descriptor record; this I/O is not done if item ID is
found in cache.
One read to retrieve the data from the ITEMDATA file; will not change
If the item ID is not found in the session's item ID cache, then the customary item access
checking still needs to be done. Because only a few item IDs are cached, an item ID
might not be found for a valid access, and a read of IFOLDER has to be done.
X400 Gateway Message Priority
Prior to this release, the X400-IMPORTER has set the priority of incoming messages by
using the following mapping:
X.400 Message Priority
TRANSFER Message Priority
URGENT
125
NORMAL
75
LOW
25
This mapping is not consistent with TRANSFER values of 150, 100, and 50,
respectively.
TRANSFER Release D30 Documentation Supplement— 118474
1- 11
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.
Checks are performed at server start-up to verify that the new PARAM values conform;
otherwise, the server outputs an error message and stops.
If only the param PRIORITYNORMAL is set, the X400-IMPORTER will add 50 to this
value to obtain the value for PRIORITYURGENT; it will subtract 50 for the
PRIORITYLOW value.
As an example, to get TRANSFER's default settings of 50, 100, and 150, the param
PRIORITYNORMAL should be set as follows:
PARAM PRIORITYNORMAL "100"
The X400-Exporter recognizes two new PARAMs indicating which X.400 priority to
use for Transfer priorities.
PARAM MAXPRINORMAL
PARAM MAXPRILOW
(Default 124)
(Default 74)
For TRANSFER messages with priority > MAXPRINORMAL, the Exporter sets the
X.400 message to URGENT. For TRANSFER messages <= MAXPRILOW, the X.400
message is marked LOW, and for priorities > MAXPRILOW and <=
MAXPRINORMAL the X.400 message is NORMAL.
The value of MAXPRINORMAL must be greater than MAXPRILOW. If only the
PARAM MAXPRINORMAL is given, the value for MAXPRILOW is
MAXPRINORMAL - 50. If it is a negative number, then MAXPRILOW =
MAXPRINORMAL/2.
X.400 Probes
The TRANSFER X400 Gateway supports X.400 probes, both incoming and outgoing.
Outgoing Probes Generated by a TRANSFER Application
To generate a probe from TRANSFER that reports back on an X.400 O/R Name, the
application can use the existing ALTER-ITEM-DESCR-XXX UOWs. The PROBEMSG field of the DELIV-CONTROL-FLAGS, when set to “Y”, signals that this item is
a probe. (Prior to this release, TRANSFER required that this field be set to N.)
To create a probe message:
1. Use CREATE-ITEM, set the item type to 109 (ORIGINAL) and set the IS-PKGHDR flag to “Y.”
1- 12
118474 —TRANSFER Release D30 Documentation Supplement
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.
Reports on Probes Generated by a TRANSFER Application
If the probe is unsuccessful, then the X.400 system responsible for a given X.400
recipient returns a Non-Delivery report. Likewise, if the application set the DELIVNOTIFY field for the recipient, and the probe is successful, the responsible X.400
system issues a Delivery report.
The X400 Importer, upon receipt of either a Delivery or Non-Delivery report, creates a
STATUS package addressed to the TRANSFER correspondent who originated the
probe.
X.400 does not include a field in either a Delivery or Non-Delivery report to indicate
that the reported-on message was a probe or a message. Therefore, TRANSFER uses the
existing agent selector values when creating the STATUS Package to indicate the probe's
success or failure for the given recipient:
Selector Value
25
Package Delivered to X400 Recipient
26
Package could not be Delivered to X400 Recipient
Each X.400 Delivery or Non-Delivery report can contain one or more reported-on
recipients; the X400 Importer creates a single STATUS package for each reported-on
recipient.
Identifying a Probe Report
The X.400 specification for Delivery and Non-Delivery reports does not include a flag
indicating what kind of X.400 Message the reported-on message was. In other words,
there is no way to tell if the reported-on message was a probe or a Mail Message unless
you can view the original message.
Reports contain two fields of interest: Content-Type and the Original Content. However,
both of these fields are optional, and the TRANSFER Gateway cannot depend on their
presence when building the STATUS package.
If the Original Content is present, the X400 Importer attaches it. If not, then the Importer
can use the report's Original P1 ID to search the TRANSFER database for the original
TRANSFER message. The success of this search depends on two factors: how soon the
report comes back, and the Retention Time setting for the X400 Special Folders. If the
folder's Retention Time has expired before the probe report comes back, and the
Original Content is not present, then the Importer cannot attach the Original Message.
TRANSFER Release D30 Documentation Supplement— 118474
1- 13
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. If one is present, the
Gateway passes each O/R Name to the XDIR server and retrieves the transformed name.
If there is not an XDIR, the Gateway combines the O/R Name's Surname and OrigName
fields to get the traditional CORR @NODE recipient name.
Having the TRANSFER name, converted by either method, the Gateway then uses
READ^NEXT^NAME UOW to verify the existence of the Recipient.
If READ^NEXT^NAME can locate the Recipient, then the Gateway returns a Delivery
report for that recipient if the Delivery report flag is set for that O/R Name.
If READ^NEXT^NAME cannot locate the Recipient, then the Gateway returns a NonDelivery report for that recipient, using the Reason/Diagnostic codes following.
Mapping of potential TRANSFER errors when attempting a READ^NEXT^NAME on
an incoming probe involves these codes:
Node unavailable (but does exists):
Reason:
Transfer Failure
Diagnostic:
NA
Name ambiguous
Reason:
Diagnostic:
(Comm failure)
Unable to Transfer
Ambiguous OR Name
Name not found (node exists, but name does not exist at node)
Reason:
Unable to Transfer
Diagnostic: Unrecognized OR Name
Name Server not found (node exists, but no TRANSFER sys)
Reason:
Directory Operation Unsuccessful
Diagnostic:
NA
Node does not exist:
Reason:
Directory Operation Unsuccessful
Diagnostic:
NA
Distribution List does not exist:
Reason:
Unable to Transfer
Diagnostic: DL-Expansion failure
Non-Support in TRANSFER Clients
No mechanism using current TRANSFER clients, such as M6530, exists to set the probe
flag or to create a TRANSFER probe.
1- 14
118474 —TRANSFER Release D30 Documentation Supplement
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. An M6530 user viewing a STATUS package with
multiple reported-on recips will be only aware of the first and will never know the probe
results for the extra REPORTED-ON RECIPs.
If this is a concern, the application originating the probe must only allow one X400 O/R
name per probe.
Altering X400 Gateway Folder Retention Times
While it has been possible to set the default item retention times for X400 special
folders, the minimum value was 14 days.
It is now possible to set values less than 14 days. This is not recommended, however, as
the value of 14 days is the best trade-off between performance and functionality.
Administrators that choose to use retention times lower than 14 days must set the
following TISERV param:
PARAM ALTERX400FOLDERS "TRUE"
At start-up, TISERV issues a warning that the param is set. Once TISERV is running,
administrators can enter ADMIN and alter the retention times of X400 special folders,
just like any other folder.
See “X400 Folder Retention Time Considerations,” later in this section for more
information.
Introduction to D30 TRANSFER
This subsection gives the external specifications for the D30 version of TRANSFER.
The purpose of this release is to provide compatibility with the D20 Guardian operating
system so increased system limits can be utilized.
This section describes TRANSFER's plans to use expanded system limits provided by
EXCEED. It includes the external changes required. It also gives implementation goals.
The primary objectives for this release of TRANSFER is to minimize the number of
TRANSFER processes required to run at low PINs and to allow high PIN requestors to
communicate with most TRANSFER processes.
Major Features and Functionality
The major features and functionality of the D30 version TRANSFER product include:
•
•
TRANSFER servers running at high PINs.
Queue File layout changes.
TRANSFER Release D30 Documentation Supplement— 118474
1- 15
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.
Support for High PIN Requesters
Many TRANSFER customers write Pathway applications in SCREEN COBOL that run
as requesters to TRANSFER servers. The previously mentioned changes to $RECEIVE
handling enable these requesters to run at high pins.
TRANSFER Processes and Low and High PIN Use
TRANSFER processes and many servers now run at high pins. Some servers are forced
at bind time, to run at low PINs in order to avoid problems with the following processes:
•
•
•
•
EXPRTSRV
IMPRTSRV
GFSERV
PSSERV
In a mixed network, while some nodes are running D30 TRANSFER and some are
running versions earlier than D30, all processes must be running at low PINs. Setting a
new parameter TRSetHighPin to YES in TRDEFLTS allows all TRANSFER processes
to run at high PINs except EXPRTSRV, IMPRTSRV, GFSERV, and PSSERV which
always run at low PINs.
File Formats
In order to support high PIN requesters in the Queue Manager facility, the Queue File
record layout must include a process handle. By using the FILLER field that follows the
CPU-PIN, you accomplish. The record layout and Full-Key changes, but the record
length and file size does not.
To use the D30 Queue Manager, no conversion is needed. The value of KEYLEN for the
new queue file increases from 56 to 76 because of the increase in size for Full-Key.
When the D30 Queue Manager starts up, it checks the queue file. If the queue file is in
the old format, the message “File xxxx is a pre-enlightened queue file” is logged. If the
Queue Manager is running high PIN and the queue file is in the old format, the Queue
Manager logs a message “Queue Manager is running at a high PIN” and then stops.
Only old UOWs are allowed if the queue file is in the old format. Similarly, new UOWs
1- 16
118474 —TRANSFER Release D30 Documentation Supplement
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.
10 Cpu
PIC X(1).
10 Pin
PIC X(1).
05 PHandle
PIC X(20).
05 FILLER
PIC X(52).
05 Data-Field
PIC X(.....).
66 Full-Key RENAMES Partition-Key THRU PHandle.
END
DEQ-D30 UOW
In order to support high PIN processes in the Queue Manager facility, the CPU-PIN field
of the DEQ-D30 UOW had to be expanded to contain a process handle.
If a DEQ-D30 UOW is used with a queue in the old format, the new error EINCOMPATIBLE-QFILE is returned.
DEQ-D30-UOW looks like DEQ-UOW, but has a process handle instead of CPU-PIN
and also has a different UOW-HDR. DEQ-D30-RSP looks like DEQ-RSP, but has a
process handle instead of CPU-PIN.
DEF Deq-D30-Uow.
05 Hdr
VALUE 511.
05 Flags.
10 Specific-Deq
10 Reserved1
10 Reserved2
10 Reserved3
10 Reserved4
10 Reserved5
10 Reserved6
10 Reserved7
05
05
05
05
05
05
Queue-Name
Priority
Time-Of-Enq
PHandle
Max-Data-Size
Pad-Char
TYPE Uow-Hdr.
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
TYPE
TYPE
PIC
PIC
TYPE
PIC
*
*
X(8)
X(20)
*.
X(1)
TRANSFER Release D30 Documentation Supplement— 118474
*VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
"N".
"N".
"N".
"N".
"N".
"N".
"N".
"N".
VALUE
VALUE
VALUE
VALUE
SPACES.
0.
LOW-VALUES.
LOW-VALUES.
VALUE LOW-VALUE.
1- 17
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).
PHandle
PIC X(20).
Data-Len
TYPE Max-Data-Size.
*
The format of the data in the queue entry returned by DEQ
*
should be defined by the application. This data will
*
immediately follow the Data-Len field and will be Max*
Data-Size bytes. The maximum size for the data portion *
of the response is constrained by the record size of the
*
Queue File. An example would be:
* 05 Data-Field
PIC X(100).
END
ENQ-D30 UOW
Users of the ENQ UOW have to make a choice when running high PIN processes. Either
they convert their programs to use the new ENQ-D30 UOW and RSP, or they will have
to force the Entry Manager to run at a low PIN. If the queue file is in the old format, the
ENQ-D30 UOW returns error E-INCOMPATIBLE-QFILE.
ENQ-D30-UOW looks like ENQ-UOW, but has a different UOW-HDR. ENQ-D30-RSP
looks like ENQ-RSP, but has a process handle instead of CPU-PIN.
DEF Enq-D30-Uow.
05 Hdr
TYPE Uow-Hdr. *VALUE 512.
05 Flags.
10 Notify-Wait-Manager TYPE Boolean
10 Reserved1
TYPE Boolean
10 Reserved2
TYPE Boolean
10 Reserved3
TYPE Boolean
10 Reserved4
TYPE Boolean
10 Reserved5
TYPE Boolean
10 Reserved6
TYPE Boolean
10 Reserved7
TYPE Boolean
1- 18
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
"Y".
"N".
"N".
"N".
"N".
"N".
"N".
"N".
118474 —TRANSFER Release D30 Documentation Supplement
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.
*^
OK
*^
E-BAD-TRANSACTION
*^
E-MUST-BE-YN
*^
E-RESERVED-MUST-BE-N
*^
E-INVALID-PRIORITY
*^
E-DATA-TOO-LONG
*^
E-ERR-QUEUE-FILE
*^
E-IO-TIMEOUT
*^
E-WAITMANAGER-UNAVAIL
*^
E-INCOMPATIBLE-QFILE
05 Retn-Code-Detail
TYPE Uow-Retn-Code-Detail.
05
05
Time-Of-Enq
PHandle
PIC
PIC
X(8).
X(20).
END
READQ-D30 UOW
If the READQ-D30 UOW is used and the queue file is in the old format, the new error
E-INCOMPATIBLE-QFILE is returned.
READQ-D30-UOW looks like READQ-UOW, but has a different UOW-HDR, has
ANY-PHANDLE to replace ANY-CPU-PIN flag, and has PHANDLE instead of CPUPIN. READQ-D30-RSP looks like READQ-RSP, but has a process handle instead of
CPU-PIN.
DEF Readq-D30-Uow.
05 Hdr
05 Flags.
10 Any-Queue-Name
10 Any-Priority
10 Any-Time-Of-Enq
10 Any-PHandle
10 Skip-Exact
10 Reposition
10 Reserved6
10 Reserved7
05 Queue-Name
05 Priority
05 Time-Of-Enq
05 PHandle
05 Max-Data-Size
05 Pad-Char
TYPE Uow-Hdr
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
PIC
PIC
TYPE
PIC
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
*
*
X(8)
X(20)
*.
X(1)
TRANSFER Release D30 Documentation Supplement— 118474
VALUE 514.
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
"N".
"Y".
"Y".
"Y".
"N".
"N".
"N".
"N".
SPACES.
0.
LOW-VALUES.
LOW-VALUES.
VALUE LOW-VALUE.
1- 19
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.
Uow-Retn-Code.
Uow-Retn-Code-Detail.
*.
*.
X(8).
X(20).
Max-Data-Size.
the actual format of the data
ENQ-TIMED-D30 UOW
If the ENQ-TIMED-D30 UOW is used and the queue file is in the old format, the new
error E-INCOMPATIBLE-QFILE is returned.
ENQ-TIMED-D30-UOW looks like ENQ-TIMED-UOW, but has a different UOWHDR. ENQ-TIMED-D30-RSP looks like ENQ-TIMED-RSP, but has a process handle
instead of CPU-PIN.
DEF Enq-Timed-D30-Uow.
05 Hdr
TYPE Uow-Hdr VALUE 513.
05 Flags.
10 Notify-Wait-Manager TYPE Boolean
VALUE "Y".
10 Effective-Now
TYPE Boolean
VALUE "N".
10 Rel-Effective-Time TYPE Boolean
VALUE "N".
10 Reserved3
TYPE Boolean
VALUE "N".
10 Reserved4
TYPE Boolean
VALUE "N".
10 Reserved5
TYPE Boolean
VALUE "N".
10 Reserved6
TYPE Boolean
VALUE "N".
10 Reserved7
TYPE Boolean
VALUE "N".
05 Effective-Time
TYPE Abs-Or-Rel-Time.
05 Queue-Name
TYPE *
VALUE SPACES.
05 Priority
TYPE *
VALUE 0.
05 Data-Byte-Count
TYPE Max-Data-Size VALUE 0.
*
*
Applications should define the actual format of the data
*
portion.
1- 20
118474 —TRANSFER Release D30 Documentation Supplement
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.
X(8).
X(20).
Message Counting
TRANSFER now, optionally, collects message counts from TISERV, TWORK, and
TRECV. The following information is collected:
•
•
•
•
Messages created locally
Messages delivered counted by the node originating package header
Messages received from the remote node counted by node
Messages sent to a remote node counted by node
This information is stored in new system PROFILE records with the following structure:
The count for local submits:
*
*
05 MCI-Submit-Count-info.
Profile Rec-Type = 951
Rec-seq-num 1 = 1st, 2 = 2nd and 3 = 3rd Class
10 Reset-timestamp
TYPE BINARY 64.
10 Last-Update-timestamp
TYPE BINARY 64.
10 Message-count
TYPE BINARY 32.
10 FILLER
PIC X(28).
The count of local deliveries, messages sent to remote nodes, and messages received
from remote nodes:
*
*
*
05 MCI-Message-Count-info.
Profile Rec-Type = 952 = Local Deliveries
953 = Sends to remote nodes
954 = Received from remote nodes
TRANSFER Release D30 Documentation Supplement— 118474
1- 21
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.
The records are stored as system control. The update count is always set to 0 so it does
not overflow. Although there is an update timestamp in the record, it is not available
through the UOW interface, so a last update timestamp is included in the data portion.
If the message-count exceeds Binary 32, then the value is set to -1D and not
incremented. A binary 32 value holds 4,294,967,295 messages before an overrun
condition occurs. It is assumed that a user program periodically collects the data and
resets the counters. (For a TRANSFER system generating 10 messages a second, the
maximum counter for one year would be 315,360,000, which would not overflow the
counter.)
To minimize record locking contention, use a subtransaction will be used to update these
profile records. Some messages might be counted an extra time if the transaction is
restarted but this should not be a significant problem.
A new parameter, COUNTMESSAGES, is recognized by TISERV, TWORK, and
TRECV. It can have one of four values:
COUNTMESSAGES NONE
No counting is done. This is the default
COUNTMESSAGES MSGS
Do the counting, but do not include Delivery counts
as they are more expensive.
COUNTMESSAGES DELIVS
Do the delivery counting only.
COUNTMESSAGES BOTH
Do all the counting, messages, and deliveries.
Only the first character is checked (“N”, “M”, “D”, “B”). If it is not valid, the following
message is displayed, and the program abends.
Invalid value for COUNTMESSAGES.
or BOTH.
1- 22
Must be NONE, MSGS, DELIVS
118474 —TRANSFER Release D30 Documentation Supplement
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. All TISERVS, TWORKS, and TRECVS have to be notified
and all at the same time. If any are not counting, the counts are not valid.
A startup parameter can be used. If delivery counts toggle on or off, the TISERVASYNC can be stopped, altered and restarted without impact.
X400 Folder Retention Considerations
Using the ALTERX400FOLDERS parameter, the retention times of the _X400_ special
folders can be changed to less than two weeks. This subsection outlines some problems
this might produce.
“Altering X400 Gateway Folder Retention Times,” discusses how to alter the default
Item Retention Time for the _X400_ correspondent, which handles all storage for the
TRANSFER X400 Gateway.
The item retention time for these folders is set to two weeks for storing items that might
come back referenced in reports or as replied-to messages in an incoming X400
message. This solution guarantees, for at least two weeks, TRANSFER reports and
replies translated from incoming X400 messages contain the original TRANSFER
message. Without this mechanism, this assurance is not possible.
An X400 report contains the original P1 ID, but the original content is optional. The
X400 Replied-To field does not contain the contents of the original message, but only
the original P2 ID. These are X400 IDs, not TRANSFER IDs.
Unless the referenced item is stored in a folder at the Gateway Node, the Gateway has
no way to attach the original TRANSFER item. And, if the item is unavailable for
attaching, the user reading the report or reply would have no idea which message the
current message is reporting about or replying to.
As an example, there is a TRANSFER user on Node A, a Gateway node B, and an X400
system. When the TRANSFER correspondent sends a message to an X400
correspondent, the following occurs:
•
•
•
•
The TRANSFER message goes from Node A to the Gateway Node B.
At Node B, the Exporter translates the TRANSFER message into an X400 message.
This message comprises two parts: the P2, which is (more or less) the contents of
the message, and the P1, which is (more or less) the envelope used for routing.
Before sending the X400 message, the Exporter makes two mapping entries in the
TRANSFER database: an ItemID-to-P1ID entry, and an ItemID-to-P2ID entry. The
Exporter also files the original Item in an _X400_ folder.
When the X400 message is forwarded by the X400 system, the contents and all
references to it are deleted from the X400 database.
TRANSFER Release D30 Documentation Supplement— 118474
1- 23
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).
If the (optional) Original Contents are not included in the report, the Importer
extracts the Original P1 Id from the report and searches the TRANSFER database
for the ItemID-to-P1ID entry.
If the Importer finds an entry – this means the item is still in one of its folders – it
attaches the original item to the report.
If it does not find the entry, the Importer attaches an EXPIRED item to the
TRANSFER report.
The user who sent the message will notice a difference between the two reports to the
TRANSFER user who sent the message. If the original is attached, then the user is
aware of exactly which message did not get delivered.
If, instead, the EXPIRED Item is present, then the user gets a Non-Delivery report with:
“The message is no longer available for display,” and has no idea which message did not
get delivered.
Replied-To messages work the same way. If the X400 correspondent sends back a reply
to the TRANSFER user, then:
•
•
•
The Importer builds a TRANSFER message extracts the Replied-To P2 ID from the
P2 message and searches the TRANSFER database for the ItemID-to-P2ID entry.
If the Importer finds an entry – this means the item is still in one of its folders – it
attaches the original item.
If the Importer does not find the entry, it attaches an EXPIRED Item.
If you are using the TRANSFER product, and if the original is attached, you are aware
of exactly which message is being replied. Otherwise, you see the following:
In Reply To:
"The message is no longer available for display."
Consider messages sent on a Friday and replied to on Monday, the next working day.
This three-day interval exceed a two-day limit and the original item would be gone.
Another simplified example is the following: Two messages sent to the same X400
Correspondent with replies of “Yes” to one and “No” to the other would be useless
without the originals. Multiple messages of this nature are very confusing.
Export/Import of Binary Objects
Most messages sent through the Transfer/X.400 Gateway consist only of text or message
body parts. However, users are not restricted to only these types.
There are two other ways of transmitting information:
1- 24
118474 —TRANSFER Release D30 Documentation Supplement
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.
Nonmail Packages
A nonmail package on export is recognized by a package where the package header has
an item type that is not 100 (status package) and is not in the range of 109-114. A
nonmail package on import is recognized by a content type value that is neither 2 (P2) or
22 (P22).
The data in a package to be exported can be stored in either item data records or in a
primary external object file, but not both. If the package header has item data records
with record types not in the ranges 210-222 and 800-899, the data from those records, in
order of record type, read and appended to form the X.400 message contents. The data
will NOT have carriage return/linefeeds appended to the records.
If the data is stored in an external object file, the data is read and appended to form the
X.400 message contents. The user-values for the external object can be any value. The
file code of the external object must be 101 if it is an edit file format file; otherwise, any
value can be used for the file code.
Import of a nonmail message will stores the data in a primary external object of an item
with item type 171. The user-values are 171. The external object file has a file code 0.
Bilaterally-Defined Body Parts
A bilaterally-defined body part on export is recognized by an item within a mail package
that has an item type of 170. The item can store the data in either itemdata records or in
a primary external object file, as described earlier in subsection on the nonmail
packages.
A bilaterally-defined body part can be imported. It will be represented in the package by
an item of item type 170. The item will have either a primary external object file with
the data or, if the Importer PARAM BLDTOITEMDATA is TRUE, in item data records.
This item is attached to the package header with a component type of 170. The uservalue = 170. The external object has a file code 0.
TRANSFER Release D30 Documentation Supplement— 118474
1- 25
GETCNT Example
TRANSFER D30 Documentation Supplement
GETCNT Example
The following is an example of GETCNT used to extract count information.
! Definition MCI-SUBMIT-COUNT-INFO created on 05/03/93 at 09:26
STRUCT
MCI^SUBMIT^COUNT^INFO^DEF (*);
BEGIN
!
Profile Rec-Type = 951
!
Rec-seq-num 1 = 1st, 2 = 2nd and 3 = 3rd Class
FIXED
RESET^TIMESTAMP;
FIXED
LAST^UPDATE^TIMESTAMP;
INT(32)
MESSAGE^COUNT;
FILLER
28;
END;
! Definition MCI-MESSAGE-COUNT-INFO created on 05/03/93 at 09:26
STRUCT
MCI^MESSAGE^COUNT^INFO^DEF (*);
BEGIN
!
Profile Rec-Type = 952 = Local Deliveries !
953 = Sends to remote nodes !
954 =
Received from remote nodes !
Rec-seq-num 1 =
1st, 2 = 2nd and 3 = 3rd Class
FIXED
RESET^TIMESTAMP;
FIXED
LAST^UPDATE^TIMESTAMP;
INT(32)
TOTAL^MESSAGE^COUNT;
STRUCT
NODE[0:255];
BEGIN
INT(32)
MESSAGE^COUNT;
END;
FILLER
28;
END;
STRUCT .MCI^message^count^info ( MCI^message^count^info^def
);
INT
.MCI^submit^count^info ( MCI^submit^count^info^def )
SUBPROC reset^counter^rec ( rt , rn );
INT rt, rn;
BEGIN
IF rt = 951 THEN
data^len := $LEN ( MCI^submit^count^info )
ELSE
data^len := $LEN ( MCI^message^count^info );
MCI^message^count^info ':=' 0 & MCI^message^count^info FOR
(data^len + 1 )/2 -1 WORDS;
CALL timestamp ( ts1 );
MCI^message^count^info.reset^timestamp := fts1;
MCI^message^count^info.last^update^timestamp := fts1;
IF ( error := write^profile^rec ( rt , rn ,
MCI^message^count^info, -1 , depot^flag ,
data^len ) ) THEN
BEGIN
eprint ( "** Error %d trying to reset profile rec %d,
1- 26
118474 —TRANSFER Release D30 Documentation Supplement
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.
! Zero out so extra words are zeros
MCI^message^count^info ':=' 0 & MCI^message^count^info
FOR
( $LEN ( MCI^message^count^info ) + 1 )/2 -1 WORDS;
IF ( error := read^profile^rec ( rec^type , rec^seq^num ,
MCI^submit^count^info,
$LEN ( MCI^submit^count^info ) ,
skip^exact, depot^flag , data^len ) )
THEN
BEGIN
IF error = -4001 THEN ! not there
BEGIN
print ( "No submit^count record for class %d" ,
@rec^seq^num );
END
ELSE
BEGIN
eprint ("** Error %d trying to read submit^count
record for class %d",
@rec^seq^num );
END;
END
ELSE ! got a record, list results
BEGIN
have^counts := true;
fts1 := MCI^submit^count^info.reset^timestamp;
fts2 := MCI^submit^count^info.last^update^timestamp;
IF list^counters THEN
eprint ("Class %d: %ts5 %ts9 to %ts5 %ts9
Submits = %dl10",
@rec^seq^num , @ts1, @ts1, @ts2, @ts2,
@MCI^submit^count^info.message^count );
CALL add^MCI^info;
TRANSFER Release D30 Documentation Supplement— 118474
1- 27
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^seq^num );
END
ELSE
BEGIN
eprint( "** Error %d trying to read delivery^count
record for class %d",
@rec^seq^num );
END;
END
ELSE ! got a record, list results
BEGIN
have^counts := true;
fts1 := MCI^message^count^info.reset^timestamp;
fts2 := MCI^message^count^info.last^update^timestamp;
IF list^counters THEN
BEGIN
print ("Class %d: %ts5 %ts9 to %ts5 %ts9
Total deliveries = %dl10",
@rec^seq^num , @ts1, @ts1, @ts2, @ts2,
@MCI^message^count^info.total^message^count );
FOR i := 0 TO 255 DO
BEGIN
IF MCI^message^count^info.node[i].message^count<>
0D THEN
print ( " Node %d3 %t8: Deliveries %dl10",
@i, @node^table[i].byte,
@MCI^message^count^info.
node[i].message^count);
END;
END;
CALL add^MCI^info;
IF reset^counters THEN
CALL reset^counter^rec ( rec^type , rec^seq^num );
END;
END; ! for loop on class
1- 28
118474 —TRANSFER Release D30 Documentation Supplement
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 );
END;
END
ELSE ! got a record, list results
BEGIN
have^counts := true;
fts1 := MCI^message^count^info.reset^timestamp;
fts2 := MCI^message^count^info.last^update^timestamp;
IF list^counters THEN
BEGIN
print( "Class %d: %ts5 %ts9 to %ts5 %ts9
Total sends = %dl10",
@rec^seq^num , @ts1, @ts1, @ts2, @ts2,
@MCI^message^count^info.total^message^count );
FOR i := 0 TO 255 DO
BEGIN
IF MCI^message^count^info.node[i].message^count
<> 0D THEN
print ( " Node %d3 %t8: Sends
%dl10",
@i, @node^table[i].byte,
@MCI^message^count^info.
node[i].message^count );
END;
END;
CALL add^MCI^info;
IF reset^counters THEN
CALL reset^counter^rec ( rec^type , rec^seq^num );
END;
END; ! for loop on class
print ( " " );
! Get the receive counts
rec^type
:= 954;
FOR rec^seq^num := 1 TO 3 DO
BEGIN
TRANSFER Release D30 Documentation Supplement— 118474
1- 29
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^message^count^info.reset^timestamp;
fts2 := MCI^message^count^info.last^update^timestamp;
IF list^counters THEN
BEGIN
print ( "Class %d: %ts5 %ts9 to %ts5 %ts9
Total receives = %dl10",
@rec^seq^num , @ts1, @ts1, @ts2, @ts2,
@MCI^message^count^info.total^message^count
);
FOR i := 0 TO 255 DO
BEGIN
IF MCI^message^count^info.node[i].message^count
<> 0D THEN
print ( " Node %d3 %t8: Receives
%dl10",
@i, @node^table[i].byte,
@MCI^message^count^info.
node[i].message^count );
END;
END;
CALL add^MCI^info;
IF reset^counters THEN
CALL reset^counter^rec ( rec^type , rec^seq^num );
END;
END; ! for loop on class
1- 30
118474 —TRANSFER Release D30 Documentation Supplement