bpi.form.parserecord()

Note: bpi.form.parserecord() may be used or you may also choose to use the higher level function bpi.checkQueueEnabled() which is documented at the top of the API section and provides an easier and more convenient method for checking whether a queue has been enabled. This function uses bpi.form.parserecord().

This subroutine accepts an array read from a MultiValue item (hashed or directory) and then parses it. It assumes the MultiValue item is encoded in simple tag=value format on each line. After parsing, all of the tag names will be in the tag array and the associated value (the part to the right of the = sign) will be in the same attribute vector in the val array. A service routine (bpi.form.getval() is provided to retrieve a value for a specific tag)

Subroutine Syntax

SUBROUTINE bpi.form.parserecord( in, tag, val, status, verbose)

Param	Direction	Description
in	passed	inbound param file content as read directly from file/item
tag	returned	An array of tag names found in the ‘in’ param
val	returned	An array of values assocated with the elements of the tag array
status	returned	@FALSE if no error, otherwise a integer
verbose	passed	integer indicating level of verbosity

This routine is extremely helpful when creating param files to control the behavior of application integrations and you will find it to be very helpful when creating routing subroutines that decide whether an application should send a document to Blue Prairie Forms or to the legacy print routine. The concept is very useful while migrating some printers or some departments/locations to Blue Prairie Forms incrementally (not all at once). For example, if your project calls for replacing 100 dot-matrix impact printers with laser prints but you only have 5 laser printers installed at for print queues Q1 - Q5 and not Q6-Q100, then you may wish to inject conditional logic into your routing routine that chooses whether to call your bpi forms enabled print routine for Q1-Q5 while calling the legacy print routine for Q6-Q100.

To do this, a configuration file could be created somewhere on your system that could declare which queues had been bpi forms enabled. Here’s an example of a param file that we created for a integration with AutoShims

# CONTROL BPIFORMS_INVOICE
# Date: 10/13/2014
# Author: Bruce Decker

# This is not a program. It is a param file.
# It does not need to be compiled.
# Commented lines begin with #

# For invoice printing routines
# This param file currently support just one tag that may be
# repeated many times. The tagname is enableQueue
# which is case sensitive and it may
# be defined as a literal without quotes or it may contain a
# Multivalue pattern definition (see MultiValue basic pattern matching).

# Example 1: enable queues Q23 and Q200-299 for bpi forms
# enableQueue=Q23            <--- this enabled Q23 for BPI FORMS
# enableQueue="Q2"2N         <--- this enaabled any queue beginning
#                            with Q2 followed by two numeric
#                            chars (e.g., Q200-Q299)

# Example 2: enable Q12, Q15 and Q20-29 for bpi forms
# enableQueue=Q12
# enableQueue=Q15
# enableQueue='Q2'1N

# Example 3: enable all queues for bpiforms
# enableQueue 'Q'0N

# Place your enabled queues below the line
# --------------------------------------------------------------------
enableQueue=Q9999
enableQueue=Q843

pi.form.parserecord()

Subroutine Syntax

SUBROUTINE bpi.form.parserecord( in, tag, val, status, verbose)

Param	Direction	Description
in	passed	inbound param file content as read directly from file/item
tag	returned	An array of tag names found in the ‘in’ param
val	returned	An array of values assocated with the elements of the tag array
status	returned	@FALSE if no error, otherwise a integer
verbose	passed	integer indicating level of verbosity

# CONTROL BPIFORMS_INVOICE
# Date: 10/13/2014
# Author: Bruce Decker
# This is not a program.  It is a param file.
# It does not need to be compiled.
# Commented lines begin with #
# For invoice printing routines
# This param file currently support just one tag that may be
# repeated many times. The tagname is enableQueue
# which is case sensitive and it may
# be defined as a literal without quotes or it may contain a
# Multivalue pattern definition (see MultiValue basic pattern matching).

# Example 1: enable queues Q23 and Q200-299 for bpi forms
#  enableQueue=Q23            <--- this enabled Q23 for BPI FORMS
#  enableQueue="Q2"2N         <--- this enaabled any queue beginning
#                            with Q2 followed by two numeric
#                            chars (e.g., Q200-Q299)

# Example 2: enable Q12, Q15 and Q20-29 for bpi forms
#  enableQueue=Q12
#  enableQueue=Q15
#  enableQueue='Q2'1N

# Example 3: enable all queues for bpiforms
#  enableQueue 'Q'0N

# Place your enabled queues below the line
# --------------------------------------------------------------------

enableQueue=Q9999
enableQueue=Q843

The routing routine simply reads this record from the database and passes it to bpi.form.parserecord. This result in the tags param being populated with two ‘enableQueue’ entries and their corresponding values reside in the tags array with vectors parallel with their tags.

Now the routing routine simply needs to loop through the tags array finding all enableQueue values then checking it associated value to see of the current Queue assignment used by the app matches the Queue defined by one of these tags. When it finds a match, it calls the Blue Prairie Forms enabled print subroutine, otherwise it calls the legacy print routine.

Here is an example routing routine based on AutoShims for a invoice reprint function:

Example Routine Subroutine using bpi.form.parserecord

SUBROUTINE BPI.INVOICE.PRINT.ROUTE(IFLAG)

* Written by Bruce Decker, Blue Prairie, Inc.
* 4/20/2014
* All use subject to written license agreement
* ------------------------------------------------------------------------------
* DOCUMENTATION
* This program is a router.  That means that it makes a decision about which
* object to call based on criteria defined within the logic of this subroutine.
* Formerly, the program LEGACY.INVOICE.PRINT would have been called.  The print
* routine definitions kept in CONTROL COMPANY have been modified to call this
* program instead.  If this routing program determines that the old legacy-style
* printing should be called, then it simply calls the old LEGACY.INVOICE.PRINT
* program.
 
* However, if this program determines that the new Blue Prairie forms-enabled
* version of the printer program should be called instead, then it will call
* BPIFORMS.INVOICE.PRINT instead.  The later subroutine removes calls to the
* native spooler and instead calls the Blue Prairie forms API to create and
* schedule the printing of the document. 
*
* 10/13/14: This program contains new logic which uses the param based control
*              file parser introduced for BPIFORMS version 3.  This program will
*              determine which queue is to be used then will search the enabled queue
*              definitions in the item CONTROL BPIFORMS.INVOICE.  See this record
*              for documentation and format information..
* ------------------------------------------------------------------------------
* Modifications
*
* ------------------------------------------------------------------------------
* Include the common variables just in case we want to reference something in
* in this router

EQU colon  TO CHAR(58); * colon
EQU period TO CHAR(46); * period

*
* ------------------------------------------------------------------------------
GOSUB Init
GOSUB OpenFiles
GOSUB GetCrtPrint
GOSUB CheckEnabled
GOSUB Route
GOTO  Exit
* ------------------------------------------------------------------------------
* S u b r o u t i n e s
* ------------------------------------------------------------------------------
Init:
   pgmId   = \BPI.INVOICE.PRINT.ROUTE\
   verbose = @FALSE  
   vector  = \\  
   tags = \\  
   vals = \\
   enabled = @FALSE 
RETURN
*
CheckEnabled:
   * This routine reads the item BPIFORMS_INVOICE from control.  It will look for  
   * tags in the record called enableQueue.  There may be zero or many of these  
   * each tag will assign a queue name or pattern that should be enabled  
   * it will iterate through all instances of the BPIFORMS_INVOICE record looking  
   * for a pattern than matches the queue being passed to this routine.  If there  
   * is a match, then it sets the enabled variable to @TRUE.  This causes the   
   * routine to call the BPIFORMS enabled version of the print program rather  
   * than the old version.  This allows you to enable none, one or all printer  
   * queues used for invoice printing by simply adding a valid pattern to that  
   * item in the CONTROL file. This allows incremental deployment of bpiforms  
   * based on queue name.  See the CONTROL BPIFORMS_INVOICE record for documentation  
   * and example syntax.   
   *
   READ i.control FROM f.control, \BPIFORMS_INVOICE\ THEN  
        CALL bpi.form.parserecord( i.control, tags, vals, vector, verbose)  
        enabled = @FALSE        
        maxTags = DCOUNT( tags, @VM)
        FOR i = 1 TO maxTags UNTIL enabled
        IF tags<1,i> EQ \enableQueue\ THEN            
               IF queue = vals<1,i> OR queue MATCHES vals<1,i> THEN         
               enabled = @TRUE        
               END
        END
        NEXT i          
   END ELSE
        enabled = @FALSE
   END 
RETURN
* ------------------------------------------------------------------------------

Route:
   method = \LEGACY.INVOICE.PRINT\ ; *<-- The legacy print program name
   IF enabled THEN
       * change method and relace word LEGACY with BPIFORMS
        method = CHANGE(method, \LEGACY\, \BPIFORMS\)
   END
   CALL @method( IFLAG)
RETURN

* ------------------------------------------------------------------------------
OpenFiles:
   OPEN \CRT-PRINT\ TO f.crtprint ELSE   
        CRT pgmId:\::Fatal error.  Unable to open CRT-PRINT\   
        STOP     
   END  
   OPEN \CONTROL\ TO f.control ELSE
        CRT pgmId:\::Fatal error.  Unable to open CONTROL\
        STOP
   END
RETURN 
*
GetCrtPrint:
   bpiSession = FIELD( OCONV(\\,\UBPI.U50BB\), SPACE(1), 1)
   READ i.crtprint FROM f.crtprint, bpiSession ELSE  
        i.crtprint = \\         
   END  
   queue = TRIM( CHANGE( i.crtprint<5>, \-n\, \\)) ; *<-- vector for invoice print queue stripped of -n switch
RETURN
*  
Exit:
   RETURN