Procedures

Con-nect offers an interface (the procedure) which enables you to use an existing Natural program to replace variables in a document with actual data when the document is formatted in Con-nect.

The Natural program itself is not added to Con-nect, it is merely made known to Con-nect via a procedure definition.

The examples at the end of this document show how procedures can be added and used to create a document.

This document covers the following topics:


Types of Procedures

There are two types of procedures:

  • Pre-formatting Procedure
    Supplies values to replace variables in a document during the formatting process.

  • Post-formatting Procedure
    Initiates activities after the document formatting has been completed (can be used to update a database).

Adding a Procedure

When you add a procedure in Con-nect, you link an existing Natural program to a procedure name which can later be identified by Con-nect. This process does not bring the Natural program into Con-nect.

Issue the following command sequence from any point in Con-nect:

ADD Procedure

As a result, the "Add Procedure" screen appears.

  11:38 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS                       Add Procedure                          Friday
                                                                                
           Folder Work___________ File _______________                          
                                                                                
   Procedure Name ________________________________                              
                                                                                
      Description ____________________________________________________________  
                  ____________________________________________________________  
                  ____________________________________________________________  
                  ____________________________________________________________  
                                                                                
                                                                                
          Program ________  and Library SYSCNT2_                                
                                                                                
      Private use _  or Security Read 7  Modify 7  Copy 7                       
                                                                                
                                                                                
                                                                                
                                                                                
 Complete the information above and press ENTER to add                          
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  In    Send  Foldr Docs  Note  Cal   Flip  Last  Home   

In addition to the information which you enter in every "Add" screen (see The "Add" Screens), you must specify the following procedure definition criteria in the "Add Procedure" screen.

Procedure Name

A unique name which identifies the procedure within Con-nect. The name must not exceed 32 characters.

Program

The Natural program which is to be executed whenever a document is formatted using the "Procedure Name" specified above.

The Natural program must have been previously defined (by the Con-nect administrator, yourself or another user).

Library

The name of the Natural library in which the program is cataloged. The library defined as STEPLIB is specified by default. You can specify the current library by typing over the default. (Only the library defined as STEPLIB or the current library may be specified.)

Press ENTER to add the procedure.

The blank "Add Procedure" screen re-appears and you can add another procedure.

Linking Procedures to a Document

You can link procedures to documents which contain variables.

The first step is to add a procedure as discussed in section Adding a Procedure.

The second step is to access the "Info" screen for the document and then link the procedure to the document. Issue the INFO command in conjunction with the document:

INFO Document name

The "Info" screen appears.

  11:40 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS        Info for sample-doc                                   Friday
  Folder  Work             File                                                 
  ------------------------------------------------------------------------------
   Document Name sample-doc                                                     
     Description A document with variables that are to be replaced with data_   
                 from the database - using a procedure_______________________   
                 ____________________________________________________________   
                 ____________________________________________________________   
        Keywords _______________  _______________  _______________              
                 _______________  _______________  _______________              
  Add Procedures _            Attached/Cover Notes      Enclosures              
     Private use _      Security Read 7  Modify 7  Copy 7  Print 7              
                                                                                
 Expiration Date 4.Feb.95___    Archive on Expiration X                         
         Created    4.Feb.94    11:40 AM by Long,Sonya           LS             
        Modified    4.Feb.94    11:40 AM by Long,Sonya           LS             
          Mailed                         by                                     
       Forwarded                         by                                     
                                                                                
 Make all required changes and press ENTER to modify                            
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  In    Send  Foldr Docs  Note  Cal   Flip  Last  Home   

Mark the "Add Procedures" field with any character and press ENTER to display the "Add Procedures for Document" window.

  11:41 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS        Info for sample-doc                                   Friday
  Folder  Work             File                                                 
  ----------------------------------   +---------------------------------------+
   Document Name sample-doc            !      Add Procedures for Document      !
     Description A document with var   +---------------------------------------+
                 from the database -   ! Formatting Profile                    !
                 ___________________   !    ________________________________   !
                 ___________________   ! Pre-Format Procedures                 !
        Keywords _______________  __   !    ________________________________   !
                 _______________  __   !    ________________________________   !
  Add Procedures x            Attach   !    ________________________________   !
     Private use _      Security Rea   !    ________________________________   !
                                       ! Post-Format Procedures                !
 Expiration Date 4.Feb.95___    Arch   !    ________________________________   !
         Created    4.Feb.94    11:4   !    ________________________________   !
        Modified    4.Feb.94    11:4   !    ________________________________   !
          Mailed                       !    ________________________________   !
       Forwarded                       +---------------------------------------+
                                                                                
 Enter a command, press a PF-key, or enter * to display commands                
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  In    Send  Foldr Docs  Note  Cal   Flip  Last  Home   

Enter the names of the pre-format and/or post-format procedures (a maximum of four each) in the appropriate lines.

You can also specify a formatting profile for the document. The formatting profile you specify in the above window will only be used when the following applies in the "Format Document-name" screen or in the "Specify Document Format Options" screen (see the description of the FORMAT command in section Documents):

  • the "Profile Name" line does not contain the name of a formatting profile; and

  • the "Formatting Profile" field is marked.

Press ENTER to close the window and to link the procedures to the document.

Formatting a Document Which Has Linked Procedures

To format a document using the associated procedures, issue the FORMAT command in conjunction with the document:

FORMAT Document name

The "Format Document-name" screen is displayed. You can then format the document and display, print, file or modify it (see the description of the FORMAT command in section Documents).

The variables in the document are replaced with actual values as specified by the procedure.

You can also, for example, specify post-formatting procedures to update a database.

Managing Your Procedures

Issue the following command sequence from any point in Con-nect to display a list of all available procedures which have been made know to Con-nect:

DISPLAY Procedure

As a result, the "Display Procedures by Name" screen appears.

  11:42 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS               Display Procedures by Name                     Friday
                                                                                
  Cmd Procedure Name                 Program  Library  Folder        Date Filed 
  --- ------------------------------ -------- -------- ------------- -----------
  __  Sample-3                       SMPL3    SYSCNT2  Work             4.Feb.94
  __  Sample-6                       SMPL6    SYSCNT2  Work             4.Feb.94
  __  Personnel                      PERSON   SYSCNT2  (S)              3.Feb.94
  __  Vacation-list                  VACLIST  SYSCNT2  (S)              1.Feb.94
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
 Cmds are 1 or 2 characters from the list below (FLIP for PF-keys)              
    Command /                                                              /    
  Display  Erase    File     Modify   Send     Top                              
                                                                                

The procedures are arranged alphabetically. Your own procedures are displayed first, followed by those created by the Con-nect administrator.

The columns display the following information:

Procedure Name

The name of the procedure.

Program

The name of the Natural program to which the Con-nect procedure name refers.

Library

The name of the Natural library in which the program is cataloged.

Folder

The name of the folder in which the procedure is stored. Procedures which have been created by the Con-nect administrator are marked with (S); you can use these procedures, but cannot erase, file or modify them.

Date Filed

The date when the procedure was first filed in the cabinet.

Commands for Procedures

The command prompting line of the "Display Procedures by Name" screen shows all the commands which apply to procedures. The commands are described in section Commands. The following exceptions apply when working with procedures:

DISPLAY

The DISPLAY command displays the procedure definition criteria specified when the procedure was added. (The actual program which comprises the procedure is stored in a Natural library, and the only way to display it is via the appropriate Natural commands and statements.)

MODIFY

The MODIFY command allows you to modify the procedure definition criteria (which identifies the Natural program to Con-nect), but does not allow you to modify the Natural program itself. You can, however, specify that another Natural program be used for the procedure.

SEND

When you SEND a procedure, the "Send" screen appears; you enter addressee(s), attach a cover note (mandatory) to the procedure, and send it with the CONFIRM command, just as with any other mail item.

When the addressee displays the new mail item in the Inbasket, the cover note is shown first. A message at the bottom of the Inbasket screen says that the mail item is a procedure. To display the procedure definition criteria, the addressee must issue the QUIT command.

To use the procedure, the addressee must first FILE it and then link it to a document as discussed in section Linking Procedures to a Document.

If you want to send the actual Natural program which comprises the procedure to another user, you must use the IMPORT command to bring the program into Con-nect (see Importing to Con-nect) and then SEND it. However, this is not necessary since every user can access a Natural program.

Examples

Below are examples for the different types of procedures:

Pre-Formatting Procedure

This example is a pre-formatting procedure used to create a document that is to be sent to a specific employee, who has not yet submitted a vacation request for the current year. It uses the COMPOSE statement to replace variables in that document with information from the database when you FORMAT the document.

According to your specifications in the "Format Document-name" screen, a formatted version of the document will be displayed or printed; or a formatted copy of the document will be filed in a folder that you specify. You can also specify that a formatted copy of the document will be placed in the "Modify Document-name" screen.

A Natural program must first be created to extract the data from the database and to compute the leave which must be taken.

0010 ****************************************************************
0020 * Program Name : SMPL4 (Pre-formatting)
0030 * created by   : Sonya Long
0040 * date         : 17.Jan.94
0050 ***************************************************************
0060 DEFINE DATA LOCAL
0070 01 #NAME     (A20)
0080 01 VAC-VIEW VIEW OF EMPLOYEES
0090   02 NAME
0100   02 FIRST-NAME
0110   02 DEPT
0120   02 LEAVE-START (1:5)
0130   02 LEAVE-END   (1:5)
0140   02 LEAVE-DUE
0150 01 #DATE
0160 01 #I        (N1)
0170 01 #N        (N1)
0180 END-DEFINE
0190 *
0200 MOVE *DATE TO #DATE
0210 MOVE 'Hamson' to #NAME
0220 FIND VAC-VIEW WITH NAME EQ #NAME
0230 *
0240 FOR #I=2 TO 5
0250  IF LEAVE-START(#I)= 000000 THEN
0260    COMPUTE #N = #I - 1
0270  END-IF
0280 MOVE 5 TO #I
0290 END-FOR
0300 *
0310 IF LEAVE-START(#N)= 000000 THEN   
0320    COMPOSE ASSIGNING
0330      'FNAME'    = FIRST-NAME,
0340      'NAME'     = NAME,0350      'DEPT'     = DEPT,
0360      'LEAVEDUE' = LEAVE-DUE
0370      'DATE'     = #DATE
0380  END-IF
0390 END-FIND
0400 END

A pre-formatting procedure must not reference a level 1 GDA, otherwise the document will not be formatted correctly.

Add a document which contains variables which are to be replaced with data from the database.

he variables must be the same as those assigned in the program. Like Con-form variables, they are characterized by a preceding & (this is only valid as long as you do not redefine the variable character & with the Con-form instruction .OP VSG=character).

  11:40 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS        Modify  Vacation                                      Friday
  Folder  Work             File                          Page      1 Line      1
    ....+....10...+....20...+....30...+....40...+....50...+....60...+....70...+.
    &fname &name                                                    &date       
    &dept                                                                       
                                                                                
    Dear &fname,                                                                
                                                                                
    You have &leavedue remaining days of vacation this year. Due to a change in 
    company policy, all vacation must be taken before the end of the year.      
    Therefore, could you please notify the supervisor of your department        
    of your vacation plans for the remainder of the year.                       
    
    In addition, the office will be closed Dec. 23 through Dec. 25,   
    therefore we have inserted those three days in your vacation plan.

    Thank you for your cooperation.                                             

Enter a command, press a PF-key, or enter * to display commands                
    Command /                                          / used  1 %  Dir +  Del ,
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  Set         X     Top   Bot   Y     Flip  CX-Y  Home   

Add a procedure as described in section Adding a Procedure.

  11:42 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS                       Add Procedure                          Friday
                                                                                
           Folder Work___________ File _______________                          
                                                                                
   Procedure Name Sample-4________________________                              
                                                                                
      Description Pre-formatting procedure____________________________________  
                  ____________________________________________________________  
                  ____________________________________________________________  
                  ____________________________________________________________  
                                                                                
                                                                                
          Program SMPL4___  and Library SYSCNT2_                                
                                                                                
      Private use _  or Security Read 7  Modify 7  Copy 7                       
                                                                                
                                                                                
                                                                                
                                                                                
 Complete the information above and press ENTER to add                          
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  In    Send  Foldr Docs  Note  Cal   Flip  Last  Home   

Access the "Info" screen for the document and mark the "Add Procedures" field.

  11:45 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS        Info for Vacation                                     Friday
  Folder  Work             File                                                 
  ------------------------------------------------------------------------------
   Document Name Vacation                                                       
     Description ____________________________________________________________   
                 ____________________________________________________________   
                 ____________________________________________________________   
                 ____________________________________________________________   
        Keywords _______________  _______________  _______________              
                 _______________  _______________  _______________              
  Add Procedures x            Attached/Cover Notes      Enclosures              
     Private use _      Security Read 7  Modify 7  Copy 7  Print 7              
                                                                                
 Expiration Date 4.Feb.95___    Archive on Expiration X                         
         Created   31.Jan.94    10:19 AM by Long,Sonya           LS             
        Modified    4.Feb.94    11:45 AM by Long,Sonya           LS             
          Mailed                         by                                     
       Forwarded                         by                                     
                                                                                
 Make all required changes and press ENTER to modify                            
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  In    Send  Foldr Docs  Note  Cal   Flip  Last  Home   

Press ENTER to access the "Add Procedures for Document" window.

  11:45 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS        Info for Vacation                                     Friday
  Folder  Work             File                                                 
  ----------------------------------   +---------------------------------------+
   Document Name Vacation              !      Add Procedures for Document      !
     Description ___________________   +---------------------------------------+
                 ___________________   ! Formatting Profile                    !
                 ___________________   !    ________________________________   !
                 ___________________   ! Pre-Format Procedures                 !
        Keywords _______________  __   !    SAMPLE-4________________________   !
                 _______________  __   !    ________________________________   !
  Add Procedures x            Attach   !    ________________________________   !
     Private use _      Security Rea   !    ________________________________   !
                                       ! Post-Format Procedures                !
 Expiration Date 4.Feb.95___    Arch   !    ________________________________   !
         Created   31.Jan.94    10:1   !    ________________________________   !
        Modified    4.Feb.94    11:4   !    ________________________________   !
          Mailed                       !    ________________________________   !
       Forwarded                       +---------------------------------------+
                                                                                
 Enter a command, press a PF-key, or enter * to display commands                
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  In    Send  Foldr Docs  Note  Cal   Flip  Last  Home   

Enter the name of the procedure as a pre-format procedure and press ENTER.

FORMAT the document and mark the following fields: "Format and File" and "Pre-Format Procedures".

  11:46 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS         Format Vacation                                      Friday
  Folder    Work             File                                               
 -------------------------------------------------------------------------------
    Mark for    Formatted Display _                                             
                  Formatted Print _                                             
                  Format and File x    and Modify _                             
                                                                                
                 Starting at Page 1                                             
                   Ending at Page 999                                           
                                                                                
               Formatting Profile _                                             
                     Profile Name FPROFILE________________________              
                                                                                
    Mark to include                                                             
                                                                                
            Pre-Format Procedures x                                             
           Post-Format Procedures _                                             
                 System Variables _                                             
 -------------------------------------------------------------------------------
 Enter a command, press a PF-key, or enter * to display commands                
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  Mod   Send                          Flip        Home   

Press ENTER to file a formatted copy of the document.

When you display the formatted copy of the document, all variables have been replaced with data from the database:

  11:47 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS         Display Vacation                                     Friday
  Folder  Work             File                          Page 1       Line 1    
    ----------------------------------------------------------------------------
                                                                                
                                                                                
                                                                                
    Walter Hamson                                                   4.Feb.94    
    COMP02                                                                      
                                                                                
    Dear Walter,                                                                
                                                                                
    You have 25 remaining days of vacation this year. Due to a change in        
    company policy, all vacation must be taken before the end of the year.      
    Therefore, could you please notify the supervisor of your department        
    of your vacation plans for the remainder of the year.                       
                                                                                
    In addition, the office will be closed Dec. 23 through Dec. 25,             
    therefore we have inserted those three days in your vacation plan.          
                                                                                
 Press ENTER for next page, or type a command (FLIP for PF-keys)                
    Command /                                                              /    
  Column   Copy     Erase    Export   File     Flip     Format   Info     Modify
  Output   Page     Position Print    Quit     Send     Top      Translat       

Post-Formatting Procedure

This example is a post-formatting procedure which can be linked to the document used in the previous example and thus update the database after the document has been formatted.

A Natural program must first be created to: extract the data from the database, compute the vacation available, and update it to reflect the new leave available after the three days in December have been subtracted.

0010 ****************************************************************
0020 * Program Name : SMPL6 (Post-formatting)
0030 * created by   : Sonya Long
0040 * date         : 17.Jan.94
0050 ***************************************************************
0060 DEFINE DATA LOCAL
0070 01 VAC-VIEW VIEW OF EMPLOYEES
0080   02 NAME
0090   02 FIRST-NAME
0100   02 DEPT
0110   02 LEAVE-START (1:12)
0120   02 LEAVE-END   (1:12)
0130   02 LEAVE-DUE
0140 01 #NAME       (A20)
0150 END-DEFINE
0160 *
0170 COMPOSE EXTRACTING
0180 #NAME = 'NAME'
0190 FIND VAC-VIEW WITH NAME EQ #NAME
0200        ASSIGN LEAVE-START(1) = 2312940210        ASSIGN LEAVE-END(1)   = 251294
0220        COMPUTE LEAVE-DUE     = LEAVE-DUE - 3
0230     UPDATE
0240     END TRANSACTION
0250 END-FIND
0260 END

Add a procedure as described in section Adding a Procedure.

  11:47 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS                       Add Procedure                          Friday
                                                                                
           Folder Work___________ File _______________                          
                                                                                
   Procedure Name Sample-6________________________                              
                                                                                
      Description Post-formatting procedure___________________________________  
                  ____________________________________________________________  
                  ____________________________________________________________  
                  ____________________________________________________________  
                                                                                
                                                                                
          Program SMPL6___  and Library SYSCNT2_                                
                                                                                
      Private use _  or Security Read 7  Modify 7  Copy 7                       
                                                                                
                                                                                
                                                                                
                                                                                
 Complete the information above and press ENTER to add                          
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  Mod   Send                          Flip        Home   

Access the "Info" screen for the document, and mark the "Add Procedures" field .

Press ENTER to access the "Add Procedures for Document" window.

  11:48 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS        Info for Vacation                                     Friday
  Folder  Work             File                                                 
  ----------------------------------   +---------------------------------------+
   Document Name Vacation              !      Add Procedures for Document      !
     Description ___________________   +---------------------------------------+
                 ___________________   ! Formatting Profile                    !
                 ___________________   !    ________________________________   !
                 ___________________   ! Pre-Format Procedures                 !
        Keywords _______________  __   !    SAMPLE-4________________________   !
                 _______________  __   !    ________________________________   !
  Add Procedures x            Attach   !    ________________________________   !
     Private use _      Security Rea   !    ________________________________   !
                                       ! Post-Format Procedures                !
 Expiration Date 4.Feb.95___    Arch   !    SAMPLE-6________________________   !
         Created   31.Jan.94    10:1   !    ________________________________   !
        Modified    4.Feb.94    11:4   !    ________________________________   !
          Mailed                       !    ________________________________   !
       Forwarded                       +---------------------------------------+
                                                                                
 Enter a command, press a PF-key, or enter * to display commands                
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  In    Send  Foldr Docs  Note  Cal   Flip  Last  Home   

Enter the name of the procedure as a post-formatting procedure and press ENTER.

FORMAT the document and mark the following fields: "Pre-Format Procedures" and "Post-Format Procedures".

  11:48 AM             * * *  C O N - N E C T  3  * * *                 4.Feb.94
  Cabinet LS         Format Vacation                                      Friday
  Folder    Work             File                                               
 -------------------------------------------------------------------------------
    Mark for    Formatted Display X                                             
                  Formatted Print _                                             
                  Format and File _    and Modify _                             
                                                                                
                 Starting at Page 1                                             
                   Ending at Page 999                                           
                                                                                
               Formatting Profile _                                             
                     Profile Name FPROFILE________________________              
                                                                                
    Mark to include                                                             
                                                                                
            Pre-Format Procedures x                                             
           Post-Format Procedures x                                             
                 System Variables _                                             
 -------------------------------------------------------------------------------
 Enter a command, press a PF-key, or enter * to display commands                
    Command /                                                              /    
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Menu  Quit  Mod   Send                          Flip        Home   

Press ENTER to format the document, and to run the program (post-formatting procedure) to update the database.