Monarch Job and Program Classes

The *Entry Procedure

As part of the migration process of a program, Monarch converts the mainline C-Specs into a procedure called *Entry in the generated class.

BegClass Custcalc Extends(ASNA.Monarch.Program Access( *Public ) +
			Attributes(ActivationGroup("HardWater"))
   . . .
  DclFld Cust#    Type ( *Packed ) Len( 9,0 )   
  DclFld Cust#Ch  Type ( *Char   ) Len( 9   )
  DclFld SalesCh  Type ( *Char   ) Len( 13  )
  DclFld ReturnCh Type ( *Char   ) Len( 13  )

  BegProc *Entry Access ( *Public )
    DclSrParm Cust#Ch  By ( *Reference ) Options( *NoPass )   
    DclSrParm SalesCh  By ( *Reference ) Options( *NoPass )
    DclSrParm ReturnCh By ( *Reference ) Options( *NoPass )
    . . .
  EndProc

The *Entry Figure above shows the generated *Entry. Notice how the Parms in the *ENTRY PLIST become the parameters to the *Entry procedure.

MyJob

Each application has to be associated with a job. This is achieved via the MyJob class that extends ASNA.Monarch.Job. This class is generated by Monarch and is available to be augmented. MyJob is responsible for two main tasks: provide a connection to the databases and invoke the startup program in the application.

MyJob.MyDatabase and optionally MyJob.MyPrinterDB are defined in MyJob. MyDatabase is used for externally described data structures, for data file and data area access, and to call programs back on the server. MyPrinterDB is used to access print files. These database connections are used in two distinct forms; the commands refer to them to obtain their external definitions at compile time, and they are used at runtime to connect to the server.

When a program has to access the database at runtime, or any other of the members of the MyJob class or its base, it is necessary to obtain a reference to the instance associated with this job. This is done using the MonarchJob property provided by the base class ASNA.Monarch.Program. An example follows.

BegClass Custcalc Extends(ASNA.Monarch.Program Access( *Public ))
    . . .
    BegConstructor Access ( *Public )
        . . .
        Open CSMASTERL1  DB (MonarchJob.Database)    
        Open CMMASTERL1  DB (MonarchJob.Database)  
    EndConstructor

As we will see in a later chapter, web applications are run in a multi-threaded environment, the MonarchJob property gets the instance object of the MyJob class associated with the particular thread running the program.

The MonarchJob property has a type of ASNA.Monarch.Job, if you need to refer to members in the class that you added to MyJob, then you should cast the value of MonarchJob using the *AS operator. This example shows how to access a field called MyField.

BegClass Custcalc Extends(ASNA.Monarch.Program) Access( *Public )
. . .
  BegSr exampleSR  Access( *Public )
      DclFld X Type ( *Char  ) Len( 10 )
             X = (MonarchJob *AS MyJob).MyField
    . . .
EndClass

Alternatively, you can use the Job's built-in LDC (local data collection) to provide access to objects and values to ASNA.Monarch.Program classes.

Startup Program

One of the main functions of MyJob is to get the program call sequence going. This is done by invoking the first program in the sequence of calls. This is known as the startup program.

A console program's My Job is typically also responsible for processing the command line. The following figure shows a MyJob sample where the startup program called is CUSTPRTS.

BegClass MyJob Extends(ASNA.Monarch.Job) Access( *Public )
. . .
    BegSr ExecuteStartupProgram Access( *Protected )
        DclSrParm CustNumber Type ( *Char  ) Len( 9 )
        DclFld SendMsg       Type ( *Char  ) Len( 3 )
        Connect MyDatabase    
        Connect MyPrinterDB
        Move 'NO '  SendMsg
        Call CUSTPRTS
        DclParm    CustNumber
        DclParm    SendMsg
        EndPrograms()
     EndSr

     BegSr Main Shared(*Yes) Access(*Public)
         DclSrParm Args Type(*String) Rank(1)
         DclFld job Type(MyJob) New()
         checkParms(Args)
         job.ExecuteStartupProgram(Args[0])
     EndSr

EndClass

The Main subroutine receives the parameters from the command line in the Args array. After being validated, the job's ExecuteStartupProgram is called passing the first argument as a parameter. In this case it represents a customer number. The ExecuteStartupProgram routine connects to the databases and invokes the CUSTPRTS program. When CUSTRPRTS (and all the programs it calls) end, the EndPrograms method of ASNA.Monarch.Job is called to deactivate any program that is still active and then the Dispose method of ASNA.Monarch.Job is called. This method is typically overwritten to close databases and release any other resource kept by the job.

Additional Embedded SQL Code

The following MyJob.vr shows a typical program with the additional code highlighted for the SQL connection established for processing embedded SQL. Notice the /Error statements generated as a reminder to change the code if MS SQL Server is used.

For additional detail and other Monarch Framework classes that support embedded SQL, refer to SQL Migration Overview.

Using System
Using MyCompany.MyApplication
DclNamespace MyCompany.MyApplication.GroupAll_Job
BegClass MyJob Extends(ASNA.Monarch.WebJob) Access(*Public)
  DclDB Name(MyDatabase) DBName("*Public/DG NET Local")Access(*Public)
  DclDB Name(MyPrinterDB) DBName("DG Net Local")Access(*Public)
  // additional declarative
  DclFld ADO_Connection Type(System.Data.Odbc.OdbcConnection) Access(*Public)
/Error When using MS SQL Server, replace System.Data.Odbc.OdbcConnection with +
/System.Data.SqlClient.SqlConnection

BegFunc getDatabase Type(ASNA.isualRPG.Runtime.Database) Access(*Protected) Modifier(*Overrides)
    LeaveSR MyDatabase
EndFunc
BegFunc getPrinterDB Type(ASNA.isualRPG.Runtime.Database) Access(*Protected) Modifier(*Overrides)
    LeaveSR MyPrinterDB
EndFunc

 // additional property
BegFunc getADO_Connection Type(System.Data.Common.DbConnection) Access(*Protected) Modifier(*Overrides)
   LeaveSR ADO_Connection
EndFunc BegSr Dispose Access(*Public) Modifier(*Overrides)
    DclSrParm disposing Type(*Boolean)
    If disposing
        Disconnect MyDatabase
        Disconnect MyPrinterDB
// additional dispose of ADO_Connection
        ADO_Connection.Close()
        ADO_Connection.Dispose()
    EndIf
   *Base.Dispose(Disposing)
EndSr
BegSr ExecuteStartupProgram Access(*Protected) Modifier(*Overrides)
      Connect MyDatabase
      Connect MyPrinterDB

 // additional code for ExecuteStartupProgram for the ADO connection
      DclFld connectStr Type(*String)   
      connectStr=string.Format("Driver={{ClientAccessODBCDriver(32-bit)}}; +
         "++"System={0};DBQ={1},*USRLIBL;Uid={2};Pwd={3}", +
         MyDatabase.Server, +
         MyDatabase.DBName, +
         MyDatabase.User, +
         /* Add your password here */ )
/Error When using MS SQL Server, replace connectStr assignment with "Data Source={0};Initial +
    Catalog={1};Integrated Security=True"

        ADO_Connection = *New System.Data.Odbc.OdbcConnection( connectStr )
/Error When using MS SQL Server, replace *New System.Data.Odbc.OdbcConnection with *New System.Data.SqlClient.SqlConnection

        ADO_Connection.Open()
        CallD 'MyCompany.MyApplication.Db0720'
EndSr
EndClass 

CLProgram

Usage of CL can be divided into two major categories: System Administration and Application Coordination.

The administration of the system involves operations like the creation of user profiles and the save/restore procedures. These activities are not considered part of the application itself and Monarch does not attempt to facilitate such activities. Normal Windows^® techniques should be employed to affect these kinds of activities.

CL is used to setup the environment for RPG programs to run. The Monarch Framework, through CL Program class, provides support for CL program procedures in these areas:

• Sets up the Library List. The Library List is an ordered set of directory names associated with each application's database connection.
• Overrides database file. File Overrides are commands to replace the database file named in a CL procedure or program or to change certain parameters of the existing database file. These overrides can be applied to DBFile, PrintFile, or a WorkStnFile object. This may be especially useful for files that have been renamed or moved since the procedure or program was created. It can also be used to access a file member other than the first member.
• Maintain application parameters in data area. This covers several areas.
  A local data area is created for each job in the system. The system creates a local data area, which is initially filled with blanks, with a length of 1024 and type *CHAR. When you submit a job, the value of the submitting job's local data area is copied into the submitted job's local data area. You can use this local data area to pass information to a procedure or program without the use of a parameter list.
  Associated with each job are a set of job properties or attributes. These attributes can be programmatically accessed in CL via the RTVJOBA commands. Another of these attributes is a series of 8 switches that can be "on" or "off." RPG programs also have access to these switches via the *INUx indicators.