EMAIL and PDF Delivery Methods

Transcription

EMAIL and PDF Delivery Methods
Version 1 Release 5E
TCP/IP is a communications
facility that permits bi-directional
communication between VSE-based
software and software running on other
platforms equipped with TCP/IP.
This manual explains how to deliver data
from one host to another using EMAIL
and PDF.
Edition #1, Published November 2006, Copyright © 2006 by CSI International
Copyright © 2006 by Connectivity Systems, Incorporated
All Rights Reserved
RESTRICTED RIGHTS LEGEND
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 252.227-7013.
This material contains confidential and proprietary material
of Connectivity Systems, Inc. and may not be used in any way
without written authorization from Connectivity Systems, Inc.. This material may not be
reproduced, in whole or in part, in any way, without prior written
permission from Connectivity Systems, Inc..
Permission is hereby granted to copy and distribute this document as follows:
•
Each copy must be a complete and accurate copy.
•
All copyright notices must be retained.
•
No modifications may be made.
•
Use of each copy is restricted to the evaluation and/or promotion of
Connectivity Systems, Inc.’s TCP/IP for VSE product or in accordance with a license agreement.
Email and PDF Delivery Methods, Version 1 Release 5E
First Edition, November 2006
Published by Connectivity Systems, Inc.
8120 State Route 138, Williamsport OH 43164
Phone: 800-795-4914 Fax: 740-986-6022
E-Mail: [email protected]
Internet: http://www.e-vse.com
INTRODUCTION ..................................................................................................1
PART 1 – EMAIL - SMTP.....................................................................................3
Defining your Email client system ..................................................................................... 3
Domain name servers...................................................................................................... 3
System-wide settings ...................................................................................................... 3
Email Defaults ................................................................................................................ 4
Defining the automated Email client .............................................................................. 5
Different ways of invoking Email....................................................................................... 6
Email (SMTP) Commands.................................................................................................. 7
PRIMARY COMMANDS.......................................................................................... 7
The SET command ....................................................................................................... 12
PART 2 – EMAIL – POP3 ..................................................................................21
Email (POP3) Commands................................................................................................. 21
PRIMARY COMMANDS........................................................................................ 22
The SET command ....................................................................................................... 27
PART 3 – PDF ....................................................................................................31
PDF configuration commands .......................................................................................... 31
PART 4 – VARIABLES ......................................................................................39
General Overview ............................................................................................................. 39
Internal .............................................................................................................................. 40
Batch ................................................................................................................................. 40
Automated......................................................................................................................... 40
Copyright © 2006 by Connectivity Systems, Inc.
i
Using the EMAIL and PDF delivery methods of TCP/IP for VSE
Introduction
There are a number of ways to deliver data from one host to another. For example,
you have FTP, LPR, Email, NFS, and an assortment of other ways that are all variations
on a theme. Some people have chose to write their own transport systems as well, and
whatever each customer chooses is often the most appropriate way for his or her specific
needs.
However, sometimes people choose methods without understanding the differences.
Why would someone decide to use Email as a method of transporting data?
Some of the benefits are:
1)
2)
3)
4)
5)
A standard interface that does not need to connect to a server on a specific
user’s laptop.
Multiple deliveries to multiple locations from a single request.
Semi-connectionless, meaning that if the final destination is currently
inactive (the user has not turned on his or her PC), the transmitting of data
will still take place and will be held for the end-user.
The recipient can be anywhere and choose to review the data at anytime.
It’s a method of receivership that most people are familiar with.
Some of the limitations are:
1)
2)
3)
4)
5)
Binary data needs to be encoded in such a way that it increases in size by
around 30%, which increases data delivery time.
If a user has a limitation of how much email he or she can receive, then the
recipient’s service provider may reject the data.
Some sites use virus-checking software that will reject attachments that do
not follow company guidelines.
You may not find out for two or three days that a delivery actually failed.
Lack of 100% certainty that data actually arrived.
Many users still find that the benefits outweigh other considerations and will
therefore choose Email over other transport methods.
This document has been created to assist you in using VSE to Email data from the
mainframe to any platform around the globe.
1
Part 1 – Email - SMTP
Defining your Email client system
It is important that you configure your TCP/IP for VSE system in such a way that
all deliveries occur with the least number of problems, and in order to do that, there are
two areas of configuration that you should be concerned with.
Domain name servers
First, you must tell VSE where to find the dictionary of domain names, so TCP/IP
can find your SMTP server name and resolve it to an IP address. It is best to define a
minimum of 2 DNS servers. Defining the same DNS server multiple times does not help.
When you have multiple DNS servers defined (up to 4), the TCP/IP for VSE stack
will keep testing each one for performance and use the one with the fastest response time.
Example: DEFINE DNS1=192.168.1.1
If you do not have a DNS server, or if your company has a policy, which prevents
using one, you will have to define a name to TCP/IP for your SMTP server and associate
an IP address for it. This is done through the DEFINE NAME command.
Example: DEFINE NAME,NAME=MAIL.SERVER,IP=192.168.1.100
System-wide settings
The next thing that you need to do is setup several system-wide default variables.
Some of these are optional and will allow you to reduce the number of control statement
in your batch processing of Email. But there are those that you need to do. For example,
the Email client needs to identify your VSE system to the SMTP server, and therefore
you need to give it a name.
SET DEFAULT_DOMAIN=my.domain.name
If you will be executing Email "scripts" (LIBR files with commands to pass to the
Email client sequentially), then those will each need to be defined:
DEFINE NAME,NAME=SCRIPT,SCRIPT=SCRIPT1
which will tell the system that when SCRIPT1 is referenced, to pass SCRIPT1.L
to the email client, which is located in a VSE library
3
If you have security enabled, you will need to have a userid and a password
defined in order to be permitted to attach various files that have been secured.
DEFINE USER,ID=myname,PASSWORD=mypassword
If you have files that you are going to use as attachments, you will need to use a
DEFINE FILE command so that the Email client can find them:
DEFINE FILE,TYPE=POWER,DLBL=IJQFILE,PUBLIC=POWER
If you have written a type-1 CGI (TYPE=CGI), you can “attach” the output
generated from a CGI. Of course, the restriction is that the CGI be written in assembler
and that it uses the FILEIOHD macro in order to be used in this way.
Email Defaults
Every batch job you run, and any automated client that runs a script, will execute a
series of commands. To reduce the number of those commands, you can use the EMAIL
command in the TCP/IP for VSE initialization file. The “EMAIL” command can be
followed by any of the following values:
SMTPD – Name of the SMTP server (For sending output)
IPADDRESS - If you don’t use SMTPD, then indicate a hard-coded address
ATSIGN- The 2-byte hex value for countries outside of the USA for “@”.
FROM -Sets a default “From:” value
REPLYTO – Set a default “Reply To:” value
SUBJECT – Set a default “Subject:” value
DESTINATION - For those who don’t want to use a DEFAULT_DOMAIN
RPORT – Change the output port from the default of 25.
SOSI – For DBCS users (in-line text)
SOSI2 – For DBCS users (attachments)
USERID – For SMTP and local file access. Default: $EMAIL
PASSWORD – For SMTP and local file access. Default: $EMAIL
TRANSLATION – Default table for everything
TRMAIL – Default table for in-line text (overrides the previous one)
TRATTACHMENTS – Default table for attachments (overrides the previous two)
POPUSERID – In order to log into a remote POP3 server
POPPASSWORD – For the remote POP3 server
POP3 -Server name of a POP3 server (for receiving input)
LUSERID – For the security system if attachments are use. Default: $EMAIL
LPASSWORD – For the security system if attachments are used. Default: $EMAIL
*NOTE: the POP3 values are for the POP3 client that is used for receiving mail. The rest are for the SMTP
client. Some of the SMTP client values are used for POP3, but that will be covered elsewhere
4
Defining the automated Email client
You can send email in a number of ways. You can run a batch job to send the email,
you can execute a CICS transaction to manually enter the commands, you can write your
own interface to be invoked in a number of ways (HTTP, and so forth), or you can use
the automated Email client.
The internal automated Email client for the TCP/IP for VSE stack will monitor a
specific class in the Power queue. When there is data to be sent, it will send the power
listing then delete the file from the VSE Power queue.
In order for this to work, you will need to define an event. You will also define a
script containing a series of commands for the automated Email client to use for
processing:
DEFINE EVENT ACTION=EMAIL,CLASS=x,ID=name,
POWERSYSID=x,QUEUE=que,
RETRY=n,RETRY_TIME=nn,PRIORITY=x,
ORDER=xx,TYPE=POWER,USERID=xxxxxxx,
SCRIPTTYPE=x,HOSTNAME=zzzzzzzz,SINGLE=x
ACTION – Must be EMAIL
TYPE – Must be POWER
CLASS – The class in the Power queue to look into
QUEUE – Must be LST or PUN
ID – A unique name to identify this event
POWERSYSID – Only for Shared Spooled systems
SCRIPTTYPE – To use a file type other than “.L” for your scripts.
ORDER – To force output in the queue to be processed in the order it arrives
SINGLE – To single-thread the Email – one at a time
PRIORITY – TO establish a processing priority
RETRY – Number of times to try to send an Email after it fails
RETRY_TIME – The number of seconds to wait before retries
USERID – To limit the access to specific USER entries
HOSTNAME – USER, DEST, ROOM, DEPT, BUILDING
HOSTNAME indicates which field on the Power LST statement will contain the
name of the script to be executed. If this field does not contain a valid script name,
previously defined to the TCP/IP stack, the event will fail. The Power entry will be
modified to DISP=Y and will remain in the queue.
Normally, you do not need to use all of the fields as noted above. These operands
are explained in greater detail in other documentation
5
X
X
X
X
Different ways of invoking Email
You can either invoke the Email client through the batch interface that is provided:
// EXEC EMAIL
Or through the provided CICS transaction:
EMAIL
Or through the automated client:
DEFINE EVENT,ID=EMAIL,ACTION=EMAIL,CLASS=M,HOST=USER
Or through the use of the programmer API, by doing your own SOCKET
programming in order to activate the internal client.
In every case, the client is activated, commands are sent to it and responses are
returned from each command, indicating success or failure. When you are ready to
actually have the data sent, the “SEND” command is issued, and when you are done, you
send the “QUIT” command and then terminate the process by either having the JCL
complete, or the CICS screen clear, and so forth.
For every client, the process is identical, but the manner in which each one occurs is
different.
6
Email (SMTP) Commands
The following commands are passed to the SMTP client. When it receives them, it
will either return a “Ready” or an “Error” response. If an “Error” is returned, then the
client will abort the request (with the exception of the API, where it is up to the program
to handle any exception).
These commands are passed in different ways, depending on the client. For
example, the automated client, while issuing a few default commands, will invoke a
script to perform an Email, while for the batch client, it will read the commands from
SYSIPT, and so forth. It is important to note that the Email client cannot accept a string
longer than 100-bytes, even from a user-written API, and even if variables are used. No
matter what, the Email client will truncate it down to 100-bytes. For those using the batch
Email client, that will not be a problem in most cases. Remember, comments are ignored.
PRIMARY COMMANDS
CD – Change the working local directory. Required to attach files. The automated
client will generate this command based on the QUEUE name and CLASS
identifier. Please note that a public name of “POWER” must be defined to the
TCP/IP stack in order for the automated client to work.
CD POWER.LST.Q
Change has completed
Ready:
PWD – Print the name of the current working directory as pointed at by the last CD
command (see above) issued. There isn’t a lot of use for it outside of an interactive
system.
PWD
"POWER.LST.Q"
Ready:
DIR – Return a list of entries (files, subdirectories) in the current local directory.
The format will be based on the DOS format returned from an FTP session. In the
example below, we have a Power queue entry, showing the names, the number of
calculated bytes, the number of pages, the number of lines, the priority, disposition,
and the date and time it was created. If you added the subparameter of the file mask
(such as DIR POP*) then it would only have returned the first entry.
DIR
POP3.01029.00
TCPIP.01020.00
Ready:
283
194
6
3
275
191
3 K
3 D
09/28/05 07:31
09/28/05 06:54
7
HELP – Locates the file “CMDEM.K” and displays it to the user. This can be
modified and personalized. There is no subcommand. Below is a partial example,
and the contents will vary.
HELP
The following is a list of the Email commands:
< Primary Commands - List = All>
CD
DELETE
DIR
EXEC
- Change working directory
- Erase a file
- Produce a directory list
- Execute a script
< End of List>
Ready:
TEXT – This tells the EMAIL client that the following lines will be for the in-body
text of the message. The end-of-message indicator is “/+” by default, but you can
modify it by adding the “EOD=xx” subparameter to the TEXT command to provide
any 2-byte end-of-text indicator that you want. By default it will read the entire
record and process it. If you want the Email client to only use columns 1-72 of the
text that will follow, then include the subparameter “TRUNC=YES”.
TEXT EOD=((
Ready:
This is a test
Ready:
Of sending text
Ready:
((
(END-OF-TEXT)
Ready:
SEND – Send the Email. This should be almost the last command issued. Typically
you would use the “ATTACH” command to indicate the name of the attachment to
be delivered, but if you desire, by using “SEND filename AS filename”,
you can skip that ATTACH command, but please note that ATTACH and SEND are
mutually exclusive. It is also important to know that if you are sending the file as a
converted PDF, then you will need to end the file name with “.PDF”. Also, there is
no guarantee that the file delivered will have the exact same name as the one that
you provide. That is dependant upon the client that they are using.
As a side note, it should be understood that the Email client does not really connect
to the SMTP server until the “SEND” command is issued. So if you issue a number
of commands and never issue a “SEND”, nothing will be sent to the end-user. The
following example demonstrates this. The output is truncated for brevity.
8
SEND INITP240.L AS TEST.TXT
Establishing connection with the Daemon: EMAIL
220 mail.myserver.com.com ESMTP Sendmail …
EHLO my.domain.name
250-mail.myserver.com Hello, pleased to meet you.
250-AUTH DIGEST-MD5 CRAM-MD5
250-DELIVERBY
250 HELP
Connection has been established
Closing the connection with the Daemon: SMTP
Ready:
ATTACH – This tells the Email client to attach one or more files as attachments.
You can issue this command multiple times in a row, one for each file that you
desire to attach. The sub parameters include the name of the file, as it exists on
VSE, the optional “AS”, followed by the name of the file, as the recipient will see it.
Specific attributes, such as whether or not it will become a PDF, the CC indicator,
the truncation indicator, the FCB name, and other specifics are maintained for each
attachment. This means you can issue an ATTACH, then a series of settings, and
then another ATTACH. The attributes of each ATTACH will be unique. For
example, the following will send the file, once as a text file, and again as a PDF.
Notice the use of the “AS” optional word.
ATTACH INITP240.L AS TEST.TXT
Ready:
SET PDF=ON
Ready:
ATTACH INITP240.L TEST.PDF
Ready:
EXEC – This command, followed by a name of a library member, will cause the
commands in that member to be performed sequentially. You can have any
extension you desire, but if none is given, then “.L” is assumed. You can also
include the name of the library and sublibrary where it resides, but if none is given,
then the Email client will use the first occurrence it finds as part of the LIBDEF
search chain. In the following example, we will execute a script to set the USERID
and PASSWORD. First we will show a failure, then a successful execution.
EXEC LOGIN
Error: POPMail EXEC member not found : LOGIN.L
EXEC LOGIN
>>LOGIN
L << SET USER=emp1.csi
>>LOGIN
L << SET PASSWORD=secret
Ready:
SET USERID=(SUPPRESSED)
9
Ready:
SET PASSWORD=(SUPPRESSED)
Ready:
PALTER – If you have issued the CD command to enter the POWER subdirectory,
you can then issue a standard PALTER command to change the attributes or
location of a Power queue entry. The format is like the Power command.
PALTER LST,EMAIL,CLASS=1
1R88I OK
Ready:
PDELETE – If you have issued the CD command to enter the POWER subdirectory,
you can then issue a standard PDELETE command to remove an entry from the
Power queue. The format is like the Power command.
PDELETE LST,EMAIL
1R88I OK
Ready:
QUERY – The only subparameter is “OPTIONS”, which must be used. It will show
most of the settings that are currently in effect, based on the position that the
QUERY command was issued.
QUERY OPTIONS
SESSION NAME
USER
SOSI
CC
ECHO
CRLF
NOEJECT
DELREQ
DISP
TRUNCATION
RECFM
LRECL
BLKSIZE
PRIORITY
VCARD
VALIDATE
AUTH
Xlate (general)
Xlate (body)
Xlate (attach)
Ready:
:CSI_EMAIL
:my.userid
:Default
:NO
:NO
:YES
:NO
:YES
:KEEP
:OFF
:FB
:133
:133
:3
:NO
:NO
:NO
:US_ENG_03
:US_ENG_03
:US_ENG_03
10
QUIT – Terminates the Email client connection and session. It should be the last
command that you issue.
QUIT
QUIT acknowledged
Ready:
WAIT – The subparameter is a number that represents 1/300th of a second, or, if the
number ends with an “S”, normal clock seconds. This will cause the Email client to
pause for a period of time before continuing. With the exception of internal testing,
this parameter should be used with discretion. The following shows a wait for 5
seconds, first with 1/300th of a second, and then with normal seconds.
WAIT 1500
Ready:
WAIT 5S
Ready:
GOTO – This will cause the stream to jump to a specific location in the jobstream or
script. The subparameter is the labelname,
GOTO EOJ
Begin skipping statements
Ready:
/. – This will define a label that is used by the GOTO command. The subparameter
is the name of a label. This is the same as a DOS JCL statement. Now, remember,
that POPMAIL will keep processing, and will fail by not disconnecting properly if
you do not actually have the designated label.
/. EOJ
Stop skipping statements
Ready:
IF – This will do a comparison, and if a failure occurs, then it will “eat” the next
command that it encounters. This is useful in comparing variables to a setting.
Notice in the example that the “GOTO” is “eaten” because of a non-match.
IF &CPUID EQ 000001
Unsuccessful compare. Skipping next statement
Ready:
GOTO SKIP
Ready:
11
SAY – Echoes a string to the console. “WTO” is a synonym for SAY. In the
following example, we will output a message, and &CPUID will be replaced with
the CPUID of the VSE system that it is executing on. (See the description of
“Variables” for details on the internally defined variables.)
SAY Processing EMAIL.AUTOEXEC on &CPUID
Ready:
NOP – It doesn’t do anything, but it returns a “Ready” back to the client. With the
exception of internal testing, it is uncertain what use this could be to others, but it is
in there nonetheless.
NOP This is a test
Ready:
DELETE – The subparameter is the name of the file to delete. If you do not provide
a directory and subdirectory, it will use the current location based on the last CD
command issued. It will work with LIBR, POWER, and other directory file systems
that support deletion.
SETVAR – This will set a variable to a string value. The variable name can be up to
16 bytes long, and the string can be up to 100 bytes long. You can also use the
“SUBSTR” subcommand to set a variable to a segment of another variable, say, the
MM value of the current date that is stored in &CURDATE.
SETVAR TODAY="MONDAY"
<Variable has been set>
Ready:
SAY Processing the job on &TODAY
Ready:
The SET command
The SET command has the largest number of subparameters available to it, and so it
is being described in it’s own section.
HOST – The subparameter is the domain name or the IP address of the SMTP
server. If it is not specified, the default will be used. If the default is not specified,
then the Email request will fail. A synonym for HOST is SMTP or IP.
MAILSERVER – The subparameter is the domain name of the recipient. This will
cause the SMTP client to act like an SMTP server, and instead of using your SMTP
server to deliver the Email, it will find the Email server of the domain for which
12
you want to deliver the Email to, and send it that way. This is useful when other
methods of sending Email fail with a “forwarding error.”
TRANSLATE – This is the name of the translation table that will be used for all
parts of the Email. If none is used, then the default in the EMAIL command will be
used. If none is set, the system default translation table will be used.
TRBODY – This is the name of the translation table that will be used for only the inline body text. If none is set, the value in effect for SET TRANSLATE will be used.
TRATTACHMENT – This is the name of the translation table that will be used for
only the file attachment. If none is set, the value in effect for SET TRBODY will be
used.
FROM – This subparameter is the Email address the recipient will see as the sender.
The format, “My Name”<[email protected]> will cause the user see your
actual name in his or her Email client. There must be a FROM setting. If none is set,
the default will be used. If there is no default, the Email will not be sent.
TO – This subparameter is the Email address of the Email recipient. There must be
at least one recipient for the Email to be sent. You may use multiple occurrences of
this command to send a copy to multiple users as part of the “To:” heading of the
Email. There are no defaults.
COPY – This subparameter is the Email address of the Email recipient, who will
receive a copy of this Email. You may use multiple occurrences of this command to
send a copy to multiple users as part of the “Cc:” heading of the Email. There are
no defaults.
REPLYTO – This subparameter is an Email address, which will automatically be
inserted into the “To:” field of the recipient’s Email client, when that person presses
a “Reply” button (or any other similar way of automatically replying to the sender.
You can use this command multiple times in a row for multiple addresses to be
entered in the “To:” field when REPLY is pressed.
BLINDCOPY – This subparameter is the Email address of the Email recipient, who
will receive a blind copy of this Email. You may use multiple occurrences of this
command to send a copy to multiple users. Any recipient of the Email will not see
the name or Email address of the blind copy recipient. There are no defaults.
TOLIST – The subparameter is the name of the LIBR member (minus the
extension, which must be “.L”), which contains a list of email addresses. A “SET
TO=” will be generated for each one. “SET TO=” must not be in the member.
13
COPYLIST – The subparameter is the name of the LIBR member (just like
TOLIST) that contains a list of email addresses. A “SET COPY=” will be
generated for each one. “SET COPY=” must not be in the member.
BLINDLIST – The subparameter is the name of the LIBR member (just like
TOLIST) that contains a list of email addresses. A “SET BLINDCOPY=” will be
generated for each one. “SET BLINDCOPY=” must not be in the member.
REPLYTOLIST – The subparameter is the name of the LIBR member (just like
TOLIST) that contains a list of email addresses. A “SET REPLYTO=” will be
generated for each one. “SET REPLYTO=” must not be in the member.
SUBJECT – The subparameter is a string that will be the “Subject:” of the Email
sent. If not used, then the default will be copied, and if there is no default, then “No
Subject” will be sent to the recipient.
NOTIFY – The subparameter is an email address that you want a message delivered
to, in order to indicate that the person who received the Email looked at it. There is
no guarantee that the message will be delivered because many people disable that
feature from their Email clients for privacy.
FILETYPE – If you want to use a file type other than “.L” for your command files,
you can set it here.
INSERTS – The subparameter is the name of a PHASE that will be loaded and sent
before any attachment. It is usually used to set printer commands, and is more
relevant to LPR, but other people have been creative in using this with Email.
CRLF – Indicate the form of CRLF that you want to use. This was normally part of
the LPR protocol, but some people want to modify the attachment’s attributes, so
we left it in, but we don’t recommend setting it.
NOEJECT – This indicates if you want the first form-feed in the attachment to be
ignored. This is only used for PDF generating.
DISP – If set to DELETE, after the attachment is sent, it will be deleted (if
supported). If KEEP, it will not be deleted. KEEP is the default. If you are using
entries from the POWER Queue, here are other settings that may be of value.
KEEP - the attachment will be left in the queue after it has been delivered, and the
disposition must be either D or K.
FORCE - it will be attached, even if the DISP=Y, and then deleted.
LIMIT - only DISP=D and DISP=K members will be attached and then deleted.
HOLD – Similar to KEEP, but after it is sent, the DISP is change to L or H.
14
RECFM – This is only used for attachments that have a default RECFM you want to
override. For example, if you have defined a sequential file to TCP/IP, but the
RECFM associated with it in the DEFINE FILE is incorrect, you can correct it here.
Most of the time, you will not use this command. The subparameters for it are FB,
VB, V, F, SB, or SU. The default is FB.
LRECL – Like the previous command, it is only used to override the logical record
length of a file defined in the TCP/IP file system. For file systems, such as Power,
LIBR, and VSAMCAT, the use of such overrides is not required.
BLKSIZE – As with LRECL, this parameter is used to override the existing block
size of an attachment that is not part of Power, LIBR, or VSAMCAT.
NEWNAME – For those who do not want to use “SEND file AS newname” but
would rather simply use the command “SEND file”, this parameter will set what
the new name will be, the name as it will appear, usually, to the end user. While this
is not normally important for the batch job, it is very useful for the automated client,
allowing you to insert within your script, a name setting.
PRIORITY – The subparameter for this is HIGH, MEDIUM, or LOW. This simply
sets an indicator in the email header. When the email is received, the email client
can set a level of importance for the email. However, not all Email clients take
advantage of this.
USER – This is your special identifier for the SMTP server. If not set, it will use the
global setting established by the “EMAIL USERID” command, otherwise it will be
“$EMAIL” by default. If followed by the AUTH command (see below) it will be
used for server authentication. If you set the user identifier again after the AUTH
command, the new value will be used for access to file attachments, providing you
have security enabled. The subparameter is a 1-32 byte string.
LUSER – This is your special identifier for the VSE local security exit if an
attachment will be used. If not set, it will use global setting established by the
“EMAIL LUSER” command, otherwise it will use “$EMAIL” by default. The
subparameter is a 1-16 byte string.
PASSWORD – This is the password associated with your special identifier. If not set,
it will use the global value established by the “EMAIL PASSWORD” command,
otherwise it will be “$EMAIL” by default. If followed by the AUTH command (see
below) it will be used for server authentication. If you set the password after the
AUTH command, that new value will be used for access to file attachments,
providing you have security enabled. The subparameter is a 1-16 byte string.
LPASSWORD – This is your password for the VSE local security exit if an
attachment will be used. If not set, it will use global setting established by the
15
“EMAIL LUSER” command, otherwise it will use “$EMAIL” by default. The
subparameter is a 1-16 byte string.
AUTH – Some SMTP servers will require that you perform authentication (sending
your USERID and PASSWORD in an encoded format) before allowing you to use
their services. Once you have set the USERID, and the PASSWORD, you can issue
the SET AUTH=ON command to tell the client how to log on. If your server does
not support authentication, then it will not attempt to use this service (when you
connect to the SMTP server and give your greeting, it will return a list of all
supported commands). The only subparameter is “ON”.
ATTACHFAIL – If you don’t care whether the desired file is found or not, set the
subparameter to “ON”. If not set, and the attempt to attach the file fails (either
because it does not exist or because of a security failure), then the transaction will
terminate. This is useful if you are attaching multiple files. If one file attachment
fails, the other attachments will still be delivered. Of course, the missing file will be
sent to the user, but the user will only receive a null attachment because no data will
be transmitted. There is no facility in the Email protocol to cancel an email in the
middle of a delivery.
DEBUG – If the subparameter is set to “ON” then additional messages will be
produced on SYSLOG/SYSLST, which is useful for debugging problems.
CHECKNAME – If you don’t want the Email client to validate the format of the
Email address that was sent, then use the “ON” subparameter. This is useful for
those sites that use strange addressing formats because the recipient is a fax
machine, or some other device that requires a special format.
PDF – The subparameter is either “OFF” (don’t convert to a PDF), “ON” (read the
PDF configuration file PDFSETUP.L), or a 1-8 character name of the desired PDF
configuration file (a LIBR member name without the file type). If you do not enable
this, then the file will not be converted. If you do enable this, then it is important
that you tell the Email client that the attachment should have a file type of .PDF.
TRUNCATION – If you want the attached file to keep all of the blanks on each
record, then leave this parameter alone. If you want to strip off the rightmost blanks
of each record before attaching the file, then use the subparameter of “ON”.
CC – The subparameter is either “OFF” (the default), or “ON”. If ON, and you are
accessing a member from the Power queues, then the first column of each record of
the attachment will contain a carriage control byte (“1” for form-feed, “0” for
double spacing, and so forth).
BINARY – Normally you do not need to indicate if the attached file is binary or not.
There is a file called EXTTYPES.L, which is checked before sending an
attachment. It contains a listing of file extensions and indicates which ones are
16
binary, and which ones are not. Email assumes if the entry is not in the EXXTYPES
table, then the attachment will be treated as plain text. The file extension that is
used to compare it with is the one that the recipient will see, or the “NEWNAME”
value. If the PDF command was issued, then you need not be concerned because it
will always be treated as text and then converted and encoded and sent as a binary
file.
ECHO – The subparameter is either “OFF” (the default), or “ON”. If ON, then all of
the acknowledgement information sent from the SMTP server will be echoed back
to the client. This is useful in debugging problems with a specific server. If not
enabled, then only pertinent information will be returned to the client.
SEPARATOR - This only affects entries from the Power queue. If there are
separator pages for a particular printout, and if you set the subparameter to OFF,
(which is the default) then no separator pages will be sent with the attachment. If set
to ON, then only 1 separator page will be sent with the attachment.
DUPES – If the subparameter is set to set “OFF” (the default), then if you send an
email address that is identical to one already being used in that session, it will
ignore the duplicate. If set to “ON”, it will not perform such a check, and if you have
duplicate names, you will most likely send the same email to the same user multiple
times.
VALIDATE – If the subparameter is set to set “OFF” (the default), then text data
that is being sent will not be modified. If set to “ON”, then any attachment that is
assumed to be non-binary, will have all non-text EBCDIC characters stripped out of
it before being sent, which are X’00’-X’3F’ and X’FA’-X’FF’, which will be
replaced with blanks, before being translated to ASCII and sent to the recipient.
PORT – If your SMTP server needs a port number other than 25 (which is the
standard port number), then you would enter the replacement port number in the
subparameter. However, if you will always be using the same SMTP server, then it
would be best to set the replacement port number in the EMAIL default global
setting. A synonym for PORT is RPORT.
FCB – The subparameter is the 1-8 byte phase name of the FCB. This must be in
a library that is accessible to the TCP/IP partition, based on the LIBDEF settings. If
you set the FCB to a name, then this will also affect the PDF conversion. You can
clear this by setting the name of the FCB to “*NULL”
SOSI – This is relevant to those sites that deal with DBCS character sets. The
subparameter will either be NONE (the default), KEEP, CONVERT, XLATE, or
BLANK. It is better to set this as a global setting rather than using it in every Email
job stream.
17
VCARD – The subparameter is a 1-8 name of a VCF file. It must be in a VSE
library that is part of the TCP/IP LIBDEF search chain, and stored as binary. After
all of the other attachments are complete, the Email client will then try to attach the
VCF file to the end. For those of you who don’t know what a .VCF file is, it
contains information relating to the person who sent the Email, and the recipient
can just click on it to add that information to their address book.
ENCODE – If you are going to send the in-line message with an ISO compatible
character set and require special encoding because you will be using a non-English
language set, then you can enter the 1-16 byte name of the encoding type, and the
Email client will include this with the message so that it can be displayed properly.
You can either set the subparameter to BASE64, indicating it is a binary
representation, or 8BITMIME if it contains hex codes that are beyond the 7-bit
character sets. Typically you would leave this setting alone unless you are from a
country where the language set requires these values.
LANGUAGE – The subparameter is a 1-8 byte file name that will automatically be
assumed to have an extension of “.L”. This will tell the Email client to replace
certain letters with other letters, and will contain an escape code to turn this
translating of characters on and off. This is useful if you are going to mix languages
in the on-body text of the message. An example of “HEBREW.L” follows, which
will permit certain lower case English letters to represent Hebrew letters, when
desired, and lower-case English letters as well.
// JOB CATAL
// EXEC LIBR
A S=PRD2.TCPIP
CATALOG HEBREW.L
CHARSET=ISO-8859-8 STANDARD VISUAL-HEBREW CHARACTER SET
ESCAPE=`
a=E0
Aleph
b=E1
Beis
g=E2
Gimel
d=E3
Dales
h=E4
Heh
v=E5
Vav
z=E6
Zayin
k=E7
Ches
j=E8
Tes
y=E9
Yod
C=EA
Khaf Sofit
c=EB
Khaf
l=EC
Lamed
M=ED
Mem Sofit
m=EE
Mem
N=EF
Nun Sofit
n=F0
Nun
s=F1
Samekh
i=F2
Ayin
P=F3
Peh Sofit
p=F4
Peh
18
X=F5
x=F6
q=F7
r=F8
w=F9
t=FA
/+
/*
/&
* $$ EOJ
Tzaddi Sofit
Tzaddi
Qoph
Resh
Shin
Tav
As you can see, the lower case letter is represented, which will be replaced. Then
the hex code that will replace it is also shown. The “escape” character is set, so that
when it is used the first time, it will switch into Hebrew, and when set again, it will
return back to English. Finally, the required ISO header information is also noted.
This is useful for SBCS language sets that are other than English.
19
Part 2 – Email – POP3
Email (POP3) Commands
The following commands are passed to the POP3 client, which is either invoked by
executing the program “POPMAIL”, or through the use of an API. When the internal
client receives the commands it will either return a “Ready” or an “Error” response. If an
“Error” is returned, then the client will abort the request (with the exception of the API,
where it is up to the program to handle any exception).
You may wonder about the utility of a POPMAIL client. After all, Email itself is a
very interactive process, and certainly, if you chose to write a CGI that would use the API
to invoke this client, you would be able to create an on-line Email retrieval system that
could be used from a Web browser or CICS, and so forth. But another way of using this
is to have programs receive Email. So if a user entered an on-line transaction, and an
Email was sent out to that user, you could use a POPMAIL interface to get back a
verification email, which is typically done on the Internet these days.
There are several things you should know about the commands. The first is that
“ON” and “YES” are equivalent as well as “OFF” and “NO”. This means that the
following are identical:
SET PLAINTEXT=ON
SET PLAINTEXT=YES
Next – as you will see in the descriptions below, the command will be in RED and
the response will be in BLUE. Commands that are transformed or sent under the covers
will be in GREEN. The responses shown may not always be exactly as you will see on
your system, because some of them are dependant upon the POP3 server that you are
using.
Comments are any lines that have an asterisk (*) in the first byte of the command
record. Therefore, you can keep a command in the job stream and temporarily disable it
by changing it into a comment, or by using the GOTO statement (which is described
below.
Finally, commands are passed in different ways (with the exception of an automated
client, because there is none for POPMAIL). For example, the batch client, POPMAIL,
will read the commands from SYSIPT, and so forth. It is important to note that the
POPMAIL client, as it is with the EMAIL client, cannot accept a string longer than 100bytes, even from a user-written API, and even if variables are used, trying to have an 8byte variable name representing a 32-byte string in order to insert it at the end of an 80byte command just won’t work.
21
PRIMARY COMMANDS
CD – Change the working local directory. Required to attach files. The automated
client will generate this command based on the QUEUE name and CLASS
identifier. Please note that a public name of “POWER” must be defined to the
TCP/IP stack in order for the automated client to work.
CD POWER.LST.1
CWD completed locally for POPMail
Ready:
PWD – Print the name of the current working directory as pointed at by the last CD
command (see above) issued. There isn’t a lot of use for it outside of an interactive
system.
PWD
"POWER.LST.1"
Ready:
DIR – Return a list of entries (files, subdirectories) in the current local directory.
The format will be based on the DOS format returned from an FTP session. In the
example below, we have a Power queue entry, showing the names, the number of
calculated bytes, the number of pages, the number of lines, the priority, disposition,
and the date and time it was created. If you added the subparameter of the file mask
(such as DIR POP*) then it would only have returned the first entry.
DIR
POP3.01029.00
TCPIP.01020.00
Ready:
283
194
6
3
275
191
3 K
3 D
09/28/05 07:31
09/28/05 06:54
EXEC – This command, followed by a name of a library member, will cause the
commands in that member to be performed sequentially. You can have any
extension you desire, but if none is given, then “.L” is assumed. You can also
include the name of the library and sublibrary where it resides, but if none is given,
then the Email client will use the first occurrence it finds as part of the LIBDEF
search chain. In the following example, we will execute a script to set the USERID
and PASSWORD. First we will show a failure, then a successful execution.
EXEC LOGIN
Error: POPMail EXEC member not found : LOGIN.L
EXEC LOGIN
>>LOGIN
L << SET USER=emp1.csi
>>LOGIN
L << SET PASSWORD=secret
Ready:
22
Ready:
Ready:
QUERY – The only subparameter is “OPTIONS”, which must be used. It will show
most of the settings that are currently in effect, based on the position that the
QUERY command was issued.
QUERY OPTIONS
USER
CC
ECHO
CRLF
DISP
TRUNCATION
RECFM
LRECL
BLKSIZE
HEADERS
PLAINTEXT
RAWTEXT
Ready:
:emp1.csi
:NO
:NO
:YES
:KEEP
:OFF
:FB
:100
:100
:NO
:YES
:NO
QUIT – Terminates the Email client connection and session. It should be the last
command that you issue.
QUIT
QUIT acknowledged
Ready:
GOTO – This will cause the stream to jump to a specific location in the jobstream or
script. The subparameter is the labelname,
GOTO EOJ
Begin skipping statements
Ready:
/. – This will define a label that is used by the GOTO command. The subparameter
is the name of a label. This is the same as a DOS JCL statement. Now, remember,
that POPMAIL will keep processing, and will fail by not disconnecting properly if
you do not actually have the designated label.
/. EOJ
Ready:
23
IF – This will do a comparison, and if a failure occurs, it will “eat” the next
command that it encounters. This is useful in comparing variables to a setting.
Notice in the example that the “GOTO” is “eaten” because of a non-match.
IF &CPUID EQ 000001
Unsuccessful compare. Skipping next statement
Ready:
GOTO SKIP
Ready:
SAY – Echoes a string to the console. “WTO” is a synonym for SAY. In the
following example, we will output a message, and &CPUID will be replaced with
the CPUID of the VSE system that it is executing on. (See the description of
“Variables” for details on the internally defined variables.)
SAY Processing EMAIL.AUTOEXEC on &CPUID
Ready:
DELETE – The subparameter is the name of the file to delete. If you do not provide
a directory and subdirectory, it will use the current location based on the last CD
command issued. It will work with LIBR, POWER, and other directory file systems
that support deletion. If a delete fails, it is not considered a critical problem, so a
simple warning will be returned without an “Error:” prefix.
CD PRD2.EMAIL
CWD completed locally for POPMail
Ready:
DELETE TEST.TXT
LIBR member deleted: TEST.TXT
DELETE TEST.TXT
Unable to delete: TEST.TXT
Ready:
SETVAR – This will set a variable to a string value. The variable name can be up to
16 bytes long, and the string can be up to 100 bytes long. You can also use the
“SUBSTR” subcommand to set a variable to a segment of another variable, say, the
MM value of the current date that is stored in &CURDATE.
SETVAR CURDATE="09280520"
<Variable has been set>
Ready:
CONNECT – The optional subparameters for this are “TO destination” where
“destination” it the domain name or the IP address of the POP3 server. If you
24
have already issued a “SET HOST” or “SET POP3” command, then no
subparameters are necessary. Including the domain name at this point is useful if
you will be connecting and disconnecting from more than one POP3 server in a
single session.
CONNECT
Ready:
READ – Every entry on the POP3 server is stored in sequential order and is
therefore referenced by the position in that list. And so, the first entry is “1” and the
5th entry is “5”, and so forth. By issuing the entry number in the subparameter,
POPMAIL will retrieve the desired entry. If you wish to retrieve one long display or
member with every email combined (separated by a line of dashes as a delimiter)
then use “ALL” or “*” in place of a number, such as “READ ALL” or “READ *”.
After reading that entry, if you have issued a “SET DISP=DELETE” command,
and you have disconnected from the POP3 server, that entry will be deleted. But
until that happens, that email will remain in the server, with the same sequence
number.
READ 1
-----------------------------------From: [email protected]
…
-----------------------------------Ready:
READNEXT – This command operates like READ but there is no entry number
used. It will note what number was previously accessed, increment it by one, and
access that one. If no entry was accessed previously, then the first entry will be
accessed. If, previously, a “READ 4” was issued, then entry #5 will be accessed.
You can abbreviate READNEXT to “READN”.
READNEXT
-----------------------------------From: [email protected]
…
-----------------------------------Ready:
DISCARD – By indicating one or a series of numbers, which is the entry number of
each Email in the POP3 server, you can mark that entry for deletion. It will not be
deleted until after you disconnect from that server. Automatic discarding of entries
will take place after retrieving them if you have also used the “SET
DISP=DELETE” command. The DISCARD command will send the POP3
command “DELE”, which you will see in your SYSLST output.
25
DISCARD 1
DELE 1
+OK Message deleted..
Ready:
RESET – If you have “deleted” entries from the POP3 server, by issuing this
command before you disconnect will “undelete” everything that you have
discarded. There are no subparameters. RSET is a synonym
DISCARD 1
DELE 1
+OK Message deleted..
Ready:
RESET
Ready:
DISCONNECT – There is no subparameter for this command. It will terminate the
session with the POP3 server, and any files marked for deletion will be deleted from
the server.
DISCONNECT
Ready:
STATUS – There is no subparameter for this command. When issued it will tell
you how many entries are in the POP3 server waiting to be retrieved and the total
number of bytes they are taking.
STATUS
Messages: 32 Total bytes: 235396
Ready:
TOTALS – There is no subparameter for this command. When issued it will tell
you how many entries are in the POP3 server waiting to be retrieved and the total
number of bytes they are taking. But unlike the STATUS command, it will show
you the size of each individual entry. This is very useful in checking out what really
big file is clogging up the system.
TOTALS
*** Mailbox scan listing follows
1 39200
2 42402
3 14283
Messages: 3 Total bytes: 95885
26
LIST – There is no subparameter for this command. When issued it will display
some important information about each entry, and then produce a STATUS line at
the bottom to let you know the number of entries and their overall size. This is a
good way to look for Email from a specific user, a date, or what might be spam
trying to get into your mailbox.
LIST
---------------------------------------Entry No.: 1
Total Bytes: 39200
Date: Sat, 24 Sep 2005 23:49:52 +0200
From: [email protected]
Subject: Document
---------------------------------------Entry No.: 2
Total Bytes: 42402
Date: Sun, 25 Sep 2005 01:49:19 +0200
From: [email protected]
Subject: Re: Delivery Server
----------------------------------------Messages: 2 Total bytes: 81602
Ready:
The SET command
The SET command has the largest number of subparameters available to it, and so it
is being described in it’s own section.
HOST – The subparameter against this is the domain name or the IP address of the
SMTP server. If it is not specified, the default will be used. If the default is not
specified, then the Email request will fail. A synonym for HOST is POP3 or IP. In
the example below, you will see that if either a name or an IP address is used, then
the IP address is returned as well.
SET POP3=mail.ascinet.com
192.168.001.001
Ready:
SET IP=192.168.1.1
192.168.1.1
Ready:
TRANSLATE – The subparameter it the name of the translation table to be used. If
none is set, then the global default table is used, and if that is not set, then the
system default translation table will be used.
27
SET TRANSLATE=US_ENG_03
Ready:
DISP – If set to DELETE, after the email has been retrieved it will be marked for
deletion. If KEEP, an automatic DISCARD will not take place after retrieving the
file.
SET DISP=KEEP
Ready:
RECFM – This command, as well as the next two, are only used when storing a
retrieved entry into a VSE file system where the characteristics of that file are to be
overwritten. The valid subparameter values are F, FB, S, SV, V, and VB for Fixed,
Fixed-block, String, String-Blocked, Variable, and Variable-blocked.
SET RECFM=F
Ready:
LRECL – The subparameter for this value is a numeric value representing the
logical record length of the records to be written, if the retrieved email is to be
written to a VSE file system.
SET LRECL=133
Ready:
BLKSIZE – The subparameter for this value is a numeric value representing the
block size of the data to be written if the retrieved email is to be written to a VSE
file system.
SET BLKSIZE=133
Ready:
USERID – The 1-16 byte user ID, if it is set before “CONNECT”, will be used for
logging onto the POP3 server. If changed prior to receiving an email and attempting
to write it to a VSE file system, it will be passed to the security system (if active) to
validate access. If no user information is given, then the default value defined to the
TCP/IP Email control block will be used. When the command is passed, it is echoed
back to SYSLST, but the name is masked for security reasons. The client will then
respond with a “Ready:’ command.
SET USERID=emp1.csi
Ready:
PASSWORD – The 1-16 byte password is handled the same was as the USERID
command, since they work as a pair. When the command is passed, it is echoed
28
back to SYSLST, but the name is masked for security reasons. The client will then
respond with a “Ready:’ command.
SET PASSWORD=secretname
Ready:
DEBUG – If the subparameter is set to “ON” then additional messages will be
produced on SYSLOG/SYSLST, which is useful for debugging problems. The
default is “OFF”.
SET DEBUG=ON
Ready:
PORT – If your POP3 server needs a port number other than 110 (which is the
standard port number), then you would enter the replacement port number in the
subparameter. However, if you will always be using the same SMTP server, then it
would be best to set the replacement port number in the EMAIL default global
setting. A synonym for PORT is RPORT. The default is “110”.
SET PORT=110
Ready:
RAW – When you are downloading from your POP3 server and you just want the
raw data, the entire email as it is stored, headers and all, downloaded without
translation as a binary file, then this is the command to use, by setting the
subcommand to “YES”. This is useful for backing up or moving data from one
POP3 server to another, or for programs that want to fully examine the data as well
as any attachments. The default is “NO”.
SET RAW=YES
Ready:
HEADERS – If you do not want to have the email headers returned to you along
with the actual Email, then set the subparameter to “YES”. The headers will show
you the original host and the route it took in order to reach you. Sometimes it is
useful for determining spam, but in most cases the typical user ignores it, therefore
the default is “NO”.
SET HEADERS=YES
Ready:
PLAINTEXT – If set to “YES” this will do some basic cleanup of the Email before
delivering it, such as removing any attachments (which are UUENCODED and
unreadable), and various other settings used for formatting the data. This will make
the received email plainer to the recipient. The default is “NO”.
29
SET PLAINTEXT=YES
Ready:
TRACE – If set to “ON” this will perform a snap dump of the outgoing and
incoming datagrams. This is useful in debugging certain protocol problems. All
outgoing data will be dumped in EBCDIC. Providing that the RAW format is not
used, all incoming datagrams will be dumped in EBCDIC otherwise they will
remain untranslated. The default is “OFF”.
SET TRACE=OFF
Ready:
30
Part 3 – PDF
PDF configuration commands
The PDF generator can be invoked from the HTTP daemon, the FTP daemon, as well
as the LPR and Email (SMTP) clients. It’s task is to accept a control block that points to
an opened file, and it will then transform that file into a PDF based upon an assortment of
settings that are passed to it through the PDF configuration file, which is PDFSETUP.L,
by default, but the member name can be any valid one that the VSE library can store.
The configuration file must be a VSE librarian member, and that library must be part
of a LIBDEF search chain that is used in the TCP/IP partition.
As with most commands, you can turn it into a comment to be ignored by placing an
asterisk in the first column of that command. Also, blank lines are ignored and there is no
case sensitivity.
The following are the commands used in the definition of PDF members
FONTNAME – This is the name of the internal font that will be used for the generation
of reports. The valid names are: Courier, Helvetica, and Times-Roman. The
default is COURIER, which is a fixed-width font. This works well for most computer
reports that look as though they came off of an impact printer. As with all of the
commands, only one use of it will go into effect, and so you need to select which font
to use throughout your report, which would be one of the following:
FONTNAME=COURIER
FONTNAME=HELVETICA
FONTNAME=TIMES-ROMAN
FONTTYPE – The default for this is NORMAL. Other options are BOLD, ITALIC, or
BOLD-ITALIC. This will establish the overall font look of the report. You can
switch between these styles if you wish, which will be discussed in the next
command, but unless you want something other than “NORMAL”, then you will need
to set it as such:
FONTTYPE=BOLD
HTML – The default is “OFF”, but if you wish to use such commands within your
document, such as , , , , , B, and
so forth to switch between normal, bold, italic, and bold-italic, then you will need to
set the command to “YES” as follows:
HTML=YES
31
FONTSIZE – The default is “12”, which is the point size. Please remember that there
are 72 points to the inch, which means that at 12-points, you can get 6 lines to the
inch (unless you adjust the next command). Of course, if you use an FCB, you can
have this setting automatically done for you as you will see below, but if, for
example, you require 8 lines to the inch, you might want to use:
FONTSIZE=9
VERTICALSPACE – The default is “12”, which is the number of points from the
base of one line to the base of another. Typically you will want this number to be the
same as your point size for single-spacing, or you would double it for double-spacing
as in:
VERTICALSPACE=24
DISABLEFCB – The default is “NO”. Typically, if you set the FCB on in the
invoking client, then that attribute will be passed onto the PDF generator. For
example, if you use “SET FCB=FCBTEST” in the Email (SMTP) client, then the
FCB will be loaded into storage, and a pointer to that FCB will be passed to the PDF
generator. This will automatically override any other font and page settings (such as
the maximum lines to a page). If you don’t want an FCB to override any hard-coded
settings in your configuration file, then issue the command:
DISABLEFCB=YES
CC – The default is “YES”. Since most data being converted are actually reports from
the Power print queue, then the PDF generator will use the control character to
determine line spacing. If it finds a character other than a blank, “1”, “0”, “-“, or “+”,
then it will automatically disable this setting, assuming that the person made an error.
If you are using an FCB, then this setting should not be set to “NO” as in:
CC=NO
BARS – The default is “OFF”. This command will cause “green bar” (well, not
exactly green by default, but close!) to appear on the page. It’s easy on the eyes and a
definite paper saver! By default, the first bar appears with the top of the first line
printed (based on the next line). You can adjust that by specifying the number of
points from the top (which is an optional parameter) that you want the bar to actually
being. Since the are 72 points to the inch, of you want to start the bar ½ an inch from
the top you would use:
BARS ON,TOP=36
NOEJECT – The default is based on what may have been set by the invoking client.
Typically it is ON”, meaning that the first page eject on the first page is ignored, thus
eliminating a blank page. To counter whatever may he bee passed you can issue:
32
NOEJECT=OFF
STRIPCC – The default is ”OFF”. If you have “CC” turned off, the PDF converter
will assume that there is no carriage control in the first column and ignore it, but it
will also display those characters in the first column. If you don’t want the carriage
control to be used, and you want it stripped from the report, then issue the command:
STRIPCC=ON
IMAGE – There is no default image. The purpose of this command is to imbed an
image on the report and then produce the report (lines) over the top of it. Thus, you
may have a special form that you normally print out on your mainframe printer with
an FCB. You can use that same FCB to tell the PDF converter to adjust the line
spacing, and also have a scanned image of the form replicated on every page (it is
only imbedded one time, but internal commands tell the PDF reader to replicate it
while viewing). Alternatively, you may choose to add a logo or any other .JPG file
(the image must be a .JPG) and place it anywhere on the page. The positioning is
relative to the bottom left corner of the image, and so a position of 0,0 is the default
placement.
You must also know the dimensions of your image. You can do this a number of
ways. This is easily done if, under Windows/XP you will click once on the image and
the left side will display the dimensions for you (width and then the height).
Or, you can download any of the freeware image viewers and editors, such as at
http://www.irfanview.com and it will tell you the dimensions (width x height) as well
as allowing you to stretch and manipulate the image, including to reduce the number
of colors to limit the size of the included image.
Here is an example of doing that as well:
33
And so, if I wanted to place this single image 10 points up from the bottom and 10
points from the left of the page, and if this is stored in a VSE library under the name
of “CSILOGO.JPG”, I would use the following command:
IMAGE CSILOGO.JPG WIDTH=196 HEIGHT=177 UP=10 RIGHT=10
Use blanks, and not commas for delimiters.
Of course, there are also the DOWN and LEFT parameters as well. If you have
the lower left corned of the image originally positioned on the lower left corner of the
page, then going down will chop off some of the image at the bottom, and going left
will cut off some of the image to the left.
A final note about images:
If you have a lot of white space in the image, consider “cutting” out the white
space after a scan with an image editor. It will reduce the overall size, sometimes
significantly. Also, if the image is colorless, then use an image editor and save it with
a colorless attribute rather than 24-bit color enabled, and it too will significantly
reduce the size as well. As an example, I was able to take a black and white form that
was originally scanned at 520k and saved it as a 133k image.
KEYWORDS – If you want to imbed certain keywords in your PDF to make it easier to
find while scanning your hard drive for the right report, then you would use that
command here, such as:
KEYWORDS=”REPORT, PAYROLL, EOM, 2000”
TITLE – This is the name that the user will see in the “properties” field of the PDF
when he or she opens it, such as:
34
TITLE=”End of year payroll report”
SUBJECT – This is another piece of information that the user will see in the
“properties” field of the PDF when he or she opens it, such as:
SUBJECT=”Requested Report for Sally”
AUTHOR – This is the last of the pieces of information that you can provide the user
in the “properties” field of the PDF when he or she opens it, such as:
AUTHOR=”IS Systems””
ROTATEVALUE – The default is “0”. This value represents the number of degrees
that the form is turned in the clockwise direction. So if you wanted to view the report
upside-down, then you would use the following:
ROTATEVALUE=180
PAPERNAME – The default is “LETTER”. There are a number of standard forms that
are used, and therefore we have provided names to apply to these dimensions. If the
form you are going to use has one of the following dimensions (in points, of course!)
then you would use that name to represent the dimensions of the page to create, such
as to following for an 11”x8.5” form:
FORMNAME=LETTER,LANDSCAPE
Here is a table of the names and their dimensions (in points):
Name
A3
A3,LANDSCAPE
A4
A4,LANDSCAPE
A5
A5,LANDSCAPE
EXECUTIVE
EXECUTIVE,LANDSCAPE
LEDGER
LEDGER,LANDSCAPE
LEGAL
LEGAL,LANDSCAPE
LETTER
LETTER,LANDSCAPE
STATEMENT
STATEMENT,LANDSCAPE
TABLOID
Width
824
1190
595
842
421
595
540
720
1224
792
612
1008
612
792
396
612
396
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
Height
1190
824
842
595
595
421
720
540
792
1224
1008
612
792
612
612
396
612
35
TABLOID,LANDSCAPE
612 x
396
PAPERSIZE – What if you have a form that doesn’t fit the dimensions as
outlined in the PAPERNAME parameter? In that case, you will need to tell the PDF
generator the dimensions of the page in inches, as you normally ask for it from a
vendor in the store. So if you wanted an 8.5” by 11” form, and instead of using
the name “LETTER”, you could use:
PAPERSIZE WIDTH=8.5 HEIGHT=11
TOPBORDER – Now that we have the page size defined and all of the fonts and
attributes, we need to define the area of the page that will contain the information
from the report. This means defining the borders and the amount of data that the
page will actually hold. This parameter will tell us the number of inches from the
top, since that is the way we normally think when setting up a word processing
page on our PC. So if you wanted a 1/2” border from the top (one inch is the
default), the command would look like this:
TOPBORDER=.5
LEFTBORDER – We will not define the right border, because that is dependant
upon the data being presented. If your data runs off too far to the right, then you
will need to reduce your font size or increase you paper size. This command will
tell you where to position the beginning of each line of data being presented. By
default it is an inch, so if you want it to be a half of an inch you would use:
LEFTBORDER=.5
BOTTOMBORDER – By default, this is zero. You can adjust how many inches you
want free on the bottom of the page by using this command, or the next one (or an
FCB, of course). So if you want a half-inch border on the bottom, limiting the
lines to not run to the edge of the paper, you would use:
BOTTOMBORDER=.5
MAXLINESPERPAGE – Typically, if you entered much of the previous
information, this value will be calculated for you. This is a way of adjusting the
bottom border, although this will be overridden if you use an FCB. But this is also
good for those pages that don’t have any carriage control at all. The following is
an example:
MAXLINESPERPAGE=55
FONTWIDTH – This command will cause a font to be compressed or expanded
horizontally, while retaining it’s original height. This is useful when a slight
adjustment of the size will permit better positioning of the data. A number from
36
1% to 99% will cause the font to compress to 1% to 99% of its original size (1%
is the tightest squeeze, while 99% barely squeezes at all). A value of 100% will
not change anything and should be avoided, since it will increase the size of the
output file by several bytes per text line unnecessarily. A value of 101% to 999%
will increase the width of the font, where 101% barely widens it at all, while
999% would probably cause a single letter to take up an entire page! For example,
to squeeze a font to ½ of its original width, while retaining it’s original height,
you would use:
FONTWIDTH=50%
37
Part 4 – Variables
General Overview
The use of setting variables adds a lot of power to the process of
automating the delivery of data. For example, with a variable set automatically to
the name of the file being attached, you can include that name in the Email’s
subject heading or in the body text of the delivered message.
The implementation of variables follows the IBM implementation, with the
exception that you may extract a sub string, and besides using the dot-notation
for joining, which the IBM implementation uses, you may also use the “+” for
word concatenation.
A variable name is typically 1-16 characters long, prefixed by a “&” when
being referenced, but missing the “&” when being set, and can hold data up to
256-bytes long (however, with the restriction of the 100-byte limit for accepting
input, you will typically not need to exceed this limit).
If you want to have a variable name not translated, (to put into your text
without the setting) then you would prefix it by a pair of ampersands (“&&”) as
you would in DOS. The first ampersand will be dropped and the rest of it will be
included in the text.
If a variable name is found, then the client will scan for the end of the
name, which is typically a comma, blank, ampersand (another variable), or other
special characters. If a period is encountered, then, as with the DOS
implementation, the variable result will be appended to the next word. If you want
to include a dot between names, then, as with the DOS implementation, you
would use a pair of dots (“..”) and the first one will be dropped and the second
one will be used.
The SUBSTR command, following the SETVAR, will indicate that you
want to extract only a portion of the variable value. For example:
SETVAR X=SUBSTR(&CPUID,5,2)
will grab the last 2 digits of the 6-byte CPUID and set the variable “&X” to
whatever value that is.
As a side note, if a variable is not set, then the variable name will be
treated as though it is a name that should be left alone (treated as though it were
prefixed by a pair of “&&”).
39
Internal
There are several internal variables that are automatically set when the
Email client is being invoked through any method:
&SYSID – The 2-byte value of the “SYSID” for the TCP/IP stack controlling the
Email client.
&DOMAIN – The value of the domain (SET DOMAIN=) used for the stack that is
controlling the Email client.
&CPUID – The 6-byte field containing the CPU identifier for the VSE system
controlling the TCP/IP stack that is controlling the client.
&NOWDATE – The actual date, at the moment the variable replacement request is
being made, in format of MM/DD/YY.
&NOWTIME – The actual time, at the moment the variable replacement request is
being made, in the format of HH:MM:SS
Batch
The batch client will automatically set the following variables for you when
you perform an EXEC EMAIL:
&CURDATE – The 8-byte current date, in the format of MM/DD/YY. This is the
value set at the time the client began.
&CURTIME – The 8-byte current time in the format of HH:MM:SS. This is the
value set at the time the client began.
Automated
When the automated daemon is started, it will set a series of variables
based on the characteristics of the automatically attached file, it’s location, and
other settings.
&PWRUINF
&PWROFCB
&PWROUCB
&PWRDEST
&PWRNAME
&PWRUSRI
&CURDATE
&CURTIME
&PWRNUMB
&PWRSUFF
&PWRCOPY
–
–
–
–
–
–
–
–
–
–
–
The 1-16 byte value of the “USER=” setting of the attachment.
The 1-8 byte value of the “FCB=” setting of the attachment
The 1-8 byte value of the “UCB=” setting of the attachment
The 1-8 byte value of the “DEST=” setting of the attachment
The 1-8 byte value of the “JNM=” setting of the attachment
The 1-8 byte userid associated with creating the attachment.
The 1-8 byte date in the format of MM/DD/YY
The 1-8 byte time in the format of HH:MM:SS
The 5-byte job number of the attachment
The 3-byte segment number of the attachment
The 3-byte value of the number of “COPY=”
40
&PWRQUE
&PWRCLAS
&PWRDISP
&PWRPRTY
&PWRSID
&PWRTNOD
&PWRPRGN
&PWRROOM
&PWRDEPT
&PWRBLDG
&PWRPCNT
&PWRLCNT
&PWRDIST
&PWRFORM
&PWRFRMD
&PWRPAGD
&PWRQDAT
&PWRQTIM
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
Contains either “LST” , “PUN”, or “RDR”
Contains the 1-byte value of “CLASS=” for the output entry
Contains the 1-byte “DISP=” value for the output entry
Contains the 1-byte “PRI=” value for the output entry
Contains the 1-byte “SYSID=” value for the power queue entry
Contains the 1-8 byte target node name
Contains the 1-20 byte programmer name for the output entry
Contains the 1-8 byte room name for the output entry
Contains the 1-8 byte “DEPT=” value for the output entry
Contains the 1-8 byte building identifier for the output entry
Contains the 8-byte page count of the output entry
Contains the 8-byte line count of the output entry
Contains the 1-8 byte distribution code
Contains the 1-8 byte value from the “FNO=”
Contains the 1-6 byte “PAGEFORM=” value
Contains the 1-6 byte “PAGEDEF=” value
Contains the 8-byte date the entry was created (MM/DD/YY)
Contains the 8-byte time the entry was created (HH:MM:SS)
Along with these entries, any user-defined field name that was created as
part of the Power/VSE startup “DEFINE” commands (see the above use of
PAGEFORM and PADEDEF”) will also have variable names and values set if
they are used in the JECL of the entry that was created.
For example, if you have the following entry in your Power startup:
DEFINE L,SUBJECT,FFDE,1,60,*
And if you have in your JECL:
* $$ LST SUBJECT=’This is from me’
Then it will cause an automatic setting of:
SETVAR &SUBJECT=”This is from me”
And it can add a lot of power to your automated client processes.
41

EMAIL and PDF Delivery Methods

Transcription

Similar documents

Sample PDF

TCP Interface To Access the MICRODEM GIS

Setup Microsoft Office 2003 -2010 Step 1 For Office

Dries Harnie Elisa Gonzalez Boix Lode Hoste Andoni Lombide

RoomWizard® II Scheduling System Technical Specifications

PDF

NJR2 - 100 Delawanna Ave., Clifton, NJ

NJR3 - 100 Delawanna Ave., Clifton, NJ

Technical Specification

TCP/IP for VSE User Guide