20
Sat, Apr
5 New Articles

Fax at Your Fingertips

APIs
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

My company recently implemented Fax/400, which works well for AS/400 applications but doesn't provide an easy way to fax directly from a PC. A user can print from the PC to an AS/400 output queue by using a virtual printer but must execute a command on the AS/400 to fax the output. This is true of most AS/400 fax software. It would be nice to print from an application on a PC, have a window pop up on the PC that prompts the user for fax information, and then have the AS/400 fax the printed output automatically.

In this article, I'll show how to use the PC Support application program interfaces (APIs) to fax from a PC application transparently through an AS/400 using Fax/400. (With slight modifications you can apply this solution to any AS/400 fax software.) You'll be using PC Support APIs for the connectivity between the PC and the AS/400. By using the PC Support Virtual Print facility, you can print output from the PC to an output queue on the AS/400; you can then fax the output before it is printed.

Advanced Function Printing (AFP) drivers, which allow graphic output to be printed on an AS/400-connected printer, are included with OS/400 V2R3 for both Microsoft Windows and OS/2. PC print output directed to an AFP driver can be faxed using the Send Fax (SNDFAX) command, which is part of Fax/400. Other AS/400 fax software programs have similar capabilities.

Output queues can have a data queue attached to them. When a spooled file is placed on the output queue and the file becomes READY, an entry is placed on the data queue. With a PC Support API, you can write a program that runs on the PC and receives entries from the data queue. This entry can then be used to submit a job to the AS/400 to actually send the fax.

Follow these steps to make this happen:

1. Although it will not actually be printed, direct the print output of a PC program to an AFP printer.

2. Monitor the AS/400 data queue associated with the output queue using a PC program, so you know when the AS/400 has the document ready for printing.

3. Fax the output on the AS/400 by having the PC program submit a remote SNDFAX command to the AS/400.

Step by Step

First, the PC Support AFP drivers must be loaded on the PC. This example was tested with Windows 3.1 and Windows under OS/2. In each case, you'll need to select a printer driver to direct the PC printout to your fax software. A list of drivers is presented, including one for Fax/400.

In Windows 3.1, run the driver installation program (PCSETUPW) from the folder QIWSFL2 on the AS/400. OS/2 includes a similar driver installation program (PCSETUP2), which can be run from the QIWSOS2 folder on the AS/400. Select the Fax/400 printer driver from the list of drivers. The OS/2 driver installation program does not install the corresponding WINOS2 printer driver; it must be installed separately. The easiest way to install the driver is to load the Windows version of PC Support on the WINOS2 System and install the AFP driver as you would under Windows.

Once the AFP printer drivers are installed on the PC, create the necessary objects on the AS/400. The first object to be created is the data queue, which will receive an entry each time a spooled file is placed on the output queue. The length of the data placed on the queue is 164 bytes. Its contents are described in the IBM manual Guide to Programming for Printing and shown in 1. The data queue can be created by the following command:

Once the AFP printer drivers are installed on the PC, create the necessary objects on the AS/400. The first object to be created is the data queue, which will receive an entry each time a spooled file is placed on the output queue. The length of the data placed on the queue is 164 bytes. Its contents are described in the IBM manual Guide to Programming for Printing and shown in Figure 1. The data queue can be created by the following command:

 CRTDTAQ DTAQ(QUSRSYS/PCFAX) + MAXLEN(164) + TEXT('PC Fax Data Queue') 

Now you can create the output queue that will be used to fax. There is a data queue parameter on the Create Output Queue (CRTOUTQ) command that was included in V2R2 of OS/400 but was not documented. It is fully documented in V2R3. The output queue can now be created by the following command:

 CRTOUTQ OUTQ(QUSRSYS/PCFAX) + TEXT('PC Fax Output Queue') + DTAQ(QUSRSYS/PCFAX) 

Once the data queue and the output queue have been created, you can create the printer device with the following command:

 CRTDEVPRT DEVD(PCFAX) + DEVCLS(*LCL) TYPE(*IPDS) + MODEL(0) AFP(*YES) + AFPATTACH(*WSC) PORT(0) + SWTSET(0) ONLINE(*NO) + FONT(011) + TEXT('PC Fax Printer Device') 

Conceptually, this printer is a virtual printer. Although you have given the printer device a device class (DEVCLS) of local (*LCL) and a model number, attachment type, port, and switch setting, you have not actually attached it to a workstation controller. If the ONLINE parameter is set to *NO, the system will not try to vary it on at IPL time. The printer does not need to be varied on for this example to work. The device type must be set to *IPDS, and it's important to set the AFP parameter to *YES to correctly process graphic data.

The virtual printer configuration will need a printer file to direct the output to the correct output queue. The printer file will be connected to the PCFAX printer device and have an output queue of PCFAX. It's also necessary to give the printer file a device type (DEVTYPE) of *AFPDS. This printer file can be created with the following command:

 CRTPRTF FILE(QUSRSYS/PCFAX) + DEV(PCFAX) DEVTYPE(*AFPDS) + TEXT('PC Fax Printer File') + OUTQ(QUSRSYS/PCFAX) 

When you direct output from the PC to the AS/400 PCFAX output queue, an entry is placed on the PCFAX data queue. You can write a program on the PC that will receive an entry on the data queue and process it, but you still need the ability to have more than one PC attached to the AS/400. The program on the PC that receives data queue entries should only receive entries belonging to that PC's user.

A Complete PC Fax System

To solve this problem, you can write a simple CL program on the AS/400 that will split up the entries from the PCFAX data queue and place them on a data queue assigned to each PC user. This CL program, shown in 2, will receive an entry from the PCFAX data queue using the QRCVDTAQ API. This program should be submitted to a job queue as a never-ending program.

To solve this problem, you can write a simple CL program on the AS/400 that will split up the entries from the PCFAX data queue and place them on a data queue assigned to each PC user. This CL program, shown in Figure 2, will receive an entry from the PCFAX data queue using the QRCVDTAQ API. This program should be submitted to a job queue as a never-ending program.

You can locate the user profile that the printed output belongs to by saving the field beginning in position 23 of the received data queue entry. Check to see if there is a data queue for this user profile by calling the Check Object (CHKOBJ) command. If there is no data queue created yet, create one. The data queue entry will be sent to this queue by using the QSNDDTAQ API.

The only thing you need now is a PC program that can receive a data queue entry and process it. 3 shows an example of a C program that will receive a data queue entry, prompt the user for a phone number to fax to, then perform a Submit Remote Command on the AS/400 to actually fax the spool file using Fax/400.

The only thing you need now is a PC program that can receive a data queue entry and process it. Figure 3 shows an example of a C program that will receive a data queue entry, prompt the user for a phone number to fax to, then perform a Submit Remote Command on the AS/400 to actually fax the spool file using Fax/400.

The first action taken in the example C program is to receive an entry from the user's data queue. The important parameters on the QRCVDTAQ API are the data queue name, data, and length of data. The system name will be passed as an empty string that will use the default system name. The wait time is set to -1 to force QRCVDTAQ to wait indefinitely for an entry.

When passing data from the AS/400 to a PC, there must be a conversion of data from EBCDIC to ASCII, and vice versa. The PC Support APIs provide the most common way to do this with the QSETMODE API. The QSETMODE API can initialize the session so that all data is translated automatically.

Although this is the most common method, it is ineffective in this situation. The problem with using the QSETMODE API is that there is one field-the spooled file number-that is binary and should not be translated. If the QSETMODE API is attempted, the binary field is either translated or an error code is returned to the application. To get around this problem, receive the data in EBCDIC, convert the binary field, and then call another PC Support API- EBCTOASC-to translate the remaining data fields to ASCII.

The binary field must be manipulated for correct translation as shown in the highlighted code in 3. Numbers on an Intel CPU reverse the high- and low-order bytes within a word and the high- and low-order words within a double (or long) word, so the bytes must be moved around.

The binary field must be manipulated for correct translation as shown in the highlighted code in Figure 3. Numbers on an Intel CPU reverse the high- and low-order bytes within a word and the high- and low-order words within a double (or long) word, so the bytes must be moved around.

Once the data is translated, a command string can be built to submit the SNDFAX command. This string is then submitted to the AS/400 with the Submit Remote Command PC Support API (EHNSRSBM). A return message buffer and its length are also sent as parameters.

You now have a complete system that will allow you to fax from a PC program.

Window Dressing

This program can be enhanced with a Windows or Presentation Manager front-end graphical user interface (GUI). You may also wish to prompt for all the Fax/400 parameters and submit them as well. It would be very easy to use this example for a fax product other than Fax/400 just by changing the Submit Remote Command string.

PC Support contains a rich set of APIs that is functional and can be used for a great number of applications. If you want to go beyond the traditional connectivity methods for communicating between the AS/400 and a PC, you're limited only by your imagination and the amount of time you can afford to spend.

Fred Wiest is the director of Information Services for Grundfos Pumps Corporation, a U.S. manufacturing company and subsidiary of Grundfos Pumps International. He has more than 16 years of software development expertise in IBM midrange and PC environments. He may be contacted by Internet at This email address is being protected from spambots. You need JavaScript enabled to view it..

REFERENCES

Guide to Programming for Printing (SC41-8194, CD-ROM QBKA7702).

IBM AS/400 Printing II (Redbook GG24-3704).

PC Support/400: Application Program Interface Reference (SC41-8254, CD-ROM QBKA6102).


Fax at Your Fingertips

Figure 1 Format of Data Queue Entry for a Spooled File

 Data Name Data Type Description Function CHAR(10) Identifies the function that created the data queue entry. The value for a spooled file is *SPOOL. Record Type CHAR(2) Identifies the record type within the function. The valid value is: 01-A spooled file that has a READY status is on the output queue. Qualified CHAR(26) Identifies the qualified job name that created the Job Name spooled file. CHAR(10) Job name CHAR(10) User name CHAR(6) Job number Spooled File CHAR(10) Identifies the spooled file on the Name output queue. Spooled File BINARY(4) Identifies the unique number of the spooled file Number on the output queue. Qualified CHAR(20) Identifies the fully qualified output Output Queue queue name. Name CHAR(10) Output queue name CHAR(10) Library of the output queue Reserved CHAR(56) Reserved 
Fax at Your Fingertips

Figure 2 CL to Split PCFAX Data Queue Entries to Individual

 /*==================================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/FAX001CL) SRCFILE(XXX/QCLSRC) */ /* */ /*==================================================================*/ FAX001CL: PGM /*********************/ /* DECLARE VARIABLES */ /*********************/ DCL VAR(&RCVNAME) TYPE(*CHAR) LEN(10) VALUE(PCFAX) DCL VAR(&RCVLIB) TYPE(*CHAR) LEN(10) VALUE(*LIBL) DCL VAR(&SNDNAME) TYPE(*CHAR) LEN(10) DCL VAR(&SNDLIB) TYPE(*CHAR) LEN(10) VALUE(*LIBL) DCL VAR(&LENGTH) TYPE(*DEC) LEN(5 0) VALUE(164) DCL VAR(&WAIT) TYPE(*DEC) LEN(5 0) VALUE(-1) DCL VAR(&DATA) TYPE(*CHAR) LEN(164) /******************************/ /* RECEIVE A DATA QUEUE ENTRY */ /******************************/ LOOP: CALL PGM(QRCVDTAQ) PARM(&RCVNAME &RCVLIB &LENGTH + &DATA &WAIT) IF COND(&LENGTH *GT 0) THEN(DO) /***********************************************/ /* CREATE USER DATA QUEUE IF IT DOES NOT EXIST */ /***********************************************/ CHGVAR VAR(&SNDNAME) VALUE(%SST(&DATA 23 10)) CHKOBJ OBJ(&SNDNAME) OBJTYPE(*DTAQ) MONMSG MSGID(CPF9801) EXEC(DO) CRTDTAQ DTAQ(QUSRSYS/&SNDNAME) MAXLEN(164) TEXT('PC + FAX DTA QUEUE FOR USER' *BCAT &SNDNAME) + SENDERID(*YES) ENDDO /**********************************/ /* PLACE ENTRY ON USER DATA QUEUE */ /**********************************/ CALL PGM(QSNDDTAQ) PARM(&SNDNAME &SNDLIB &LENGTH + &DATA) ENDDO GOTO CMDLBL(LOOP) END: ENDPGM 
Fax at Your Fingertips

Figure 3 C Program to Receive Data Queue Entry

 /* Include header files */ #include  #include  #include  #include "ehndq.h" #include "ehnsrapi.h" #include "dtxlat.h" /* Define global variables */ char QueueName[22]; char SystemName[9]=""; long Wait=-1; int SenderID; char Data[164]; long DataLength=sizeof(Data); char SenderInfo[36]; char SplNbr[7]; char Phone[20]; char Job[29]; char Message[2000]; char EmptyCmd[]="SNDFAX TO( ) FILE( ) JOB( ) SPLNBR( )"; char Cmd[sizeof(EmptyCmd)]; /* Begin program */ void main(int argc, char *argv[]) { int rc; int Done=0; char SplNbrBin[4]; char *p; /* Get queue name from the first command line parameter */ memset(QueueName, ' ', sizeof(QueueName)); memcpy(QueueName, argv[1], strlen(argv[1])); /* Get an entry from the data queue */ while(!Done) { rc=QRCVDTAQ(QueueName, SystemName, Wait, SenderID, Data, &DataLength, SenderInfo); if (rc != DQ_OK) { printf(" Receive data queue failed-%d ", rc); } else { /* Ask for the fax information */ printf(" Enter Fax Number: "); gets(Phone); memcpy(Cmd, EmptyCmd, sizeof(Cmd)); /* Get the file number then translate to ASCII */ SplNbrBin[3]=Data[48]; /* Order for Intel dword/long */ SplNbrBin[2]=Data[49]; SplNbrBin[1]=Data[50]; SplNbrBin[0]=Data[51]; ltoa((unsigned long)*SplNbrBin, SplNbr, 10); memcpy(&Cmd[90], SplNbr, strlen(SplNbr)); ebctoasc(Data, Data, sizeof(Data)); /* Fill in the rest of the AS/400 command */ memcpy(&Cmd[10], Phone, strlen(Phone)); memcpy(&Cmd[37], &Data[38], 10); memset(Job, ' ', sizeof(Job)); memcpy(&Job[0], &Data[32], 6); p=strchr(Job, ' '); *p++='/'; memcpy(p, &Data[22], 10); p=strchr(Job, ' '); *p++='/'; memcpy(p, &Data[12], 10); memcpy(&Cmd[53], Job, sizeof(Job)-1); /* Issue the submit remote command */ rc=EHNSRSBM(Cmd, NULL, Message, sizeof(Message)-1); if (rc != DQ_OK) { printf(" Submit Command Failed -%d ",rc); } else { printf(" Submit Command Successful "); } } /* if (rc == DQ_OK) */ } /* While !done */ /* Stop data queues and remote command */ QSTPDTAQ(SystemName); EHNSRSTC(); } /* End main */ 
BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$0.00 Raised:
$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: