           GreenTools for Microsoft Apps(TM) (G4MS) v11.10 SP251114
--------------------------------------------------------------------
                         Installation

**Please Note**
If you are upgrading from a version prior to v5.00 and have not 
licensed the base G4MS product, please contact us for details.

If you are updating from a version prior to v8.00 please note the
names of the subprocedures have changed.  The leading # (hashtag)
has been removed on all of the functions for better compatibility
with other code pages.  You will need to update your programs to
remove the hashtag from the function names and recompile.

You can get a temporary key using the Quick Key feature www.bvstools.com.
Simply select G4MS and you will receive temporary keys for the base
product, the G4MS addons and GETURI.
                         
1. If you are installing G4MS for the first time, skip to step 2.
    If you are installing G4MS as an upgrade to a previous release,
    rename your G4MS library to G4MSOLD.  Do this by issuing the
    following command:
    
    RNMOBJ OBJ(G4MS) OBJTYPE(*LIB) NEWOBJ(G4MSOLD)

2. Issue the IBM i command: 
    CRTSAVF FILE(QGPL/G4MS)    

3. FTP the file G4MS from your PC to the IBM i in BINARY mode
    into the save file G4MS in library QGPL.

4. Issue the IBM i command:
    RSTLIB SAVLIB(G4MS) DEV(*SAVF) SAVF(QGPL/G4MS)

5. If you are installing G4MS for the first time execute the following
    commands:

    RST DEV('/qsys.lib/g4ms.lib/ifsconfig.file') 
     OBJ(('/bvstools/g4ms/*')) CRTPRNDIR(*YES) 
     PRNDIROWN(*PARENT)

    CHGAUT OBJ('/bvstools') USER(*PUBLIC) DTAAUT(*RX)
    CHGAUT OBJ('/bvstools/g4ms') USER(*PUBLIC) DTAAUT(*RX)	
    CHGAUT OBJ('/bvstools/g4ms/config') USER(*PUBLIC) DTAAUT(*RX)
    CHGAUT OBJ('/bvstools/g4ms/config/*') USER(*PUBLIC) DTAAUT(*R)   
  
6. If you are installing G4MS as an upgrade from a previous	
    version, you will want to restore the control files used
    by G4MS.   
	
    Issue the following commands:
     ADDLIBLE LIB(G4MS)
     G4MSUPDATE OLDLIB(G4MSOLD) NEWLIB(G4MS)

7.  If you are upgrading, please make sure that
     the /COPY members in QCOPYSRC were restored.  Recompile any 
     programs using the F.* service programs.

8.  Because Microsoft seems to have issues with SSL certificates on their 
     servers being incosistant, that makes it almost impossible to find
     the right Certificate Authorities (CAs) to import.  So, if you 
     want to turn off strict SSL, issue the following command:

     CHGDTAARA DTAARA(G4MS/GUSSL01DA *ALL) VALUE(*NO) 
	 
9. See the documentation for G4MS at http://docs.bvstools.com for more
    information on functionality.
   
---------------------------------------------------------------------
                          Requirements

G4MS was created on a IBM i running V7R5.  G4MS  
 requires at least V7R3 of the operating system.

G4MS requires GETURI v13.15 (included in G4MS library) or higher 
 (www.bvstools.com/geturi.html) as a base component for functionality.  
 
If you are using this with MAILTOOL you will need MAILTOOL v13.20 or higher.

Each addon included with G4MS as well as the base G4MS product
 requires separate registration.  You can
 receive temporary keys for each using the Quick key feature located
 at www.bvstools.com. 
 
This version of G4MS includes the following addons:
 G4MSDRV - One Drive Functions v8.20 
 G4MSMAIL - Send Microsoft Email v7.72
 G4MSRMAIL - Read Microsoft Email v4.00
 G4MSCAL - Calendar Function v1.00

--------------------------------------------------------------------
This version of G4MS uses the IBM i Port of the YAJL Parser provide by
 Scott Klement for JSON parsing.  Objects that make up the YAJL parser 
 are YAJL and YAJLR4 type *SRVPGM.

   Copyright (c) 2007-2015, Lloyd Hilaiel <lloyd@hilaiel.com>,
     Florian Forster  <ff at octo.it>,                       
     Scott Klement <yajl@scottklement.com>   
     
   Permission to use, copy, modify, and/or distribute this      
   software for any purpose with or without fee is hereby       
   granted, provided that the above copyright notice and this   
   permission notice appear in all copies.                                 
 ---------------------------------------------------------------------
                         Registration 

A variety of registration options are available.  Please visit:

           http://www.bvstools.com/G4MS.html           
        
---------------------------------------------------------------------                     
                              Updates 
G4MS
v1.00 - Original  
v1.10 - Updated JSON parsing routines
v1.20 - Update Service Registration to use shorter URL (from our site)
        Added scope of *OUTLOOKSMTP to allow use of OAuth 2.0 in MAILTOOL
         when using outlook mail servers. 
v1.30 - Updated to check for expiring token 2 minutes before instead of 1.
         Updated _list and _upload functions to return a -2 if the error
         was expired token.
v1.40 - Updated to use newer JSON parsion JSONTOOL v3.00 or higher for increased
         performance.
        Added G4MSUPDATE command to make updating easier.
v2.00 - Updated licensing to subscription based.
        Added folder to G4MSLSTFIL command to subset results by folder name.
        Replace JSON parsing with the IBM i port of the YAJL JSON parser provided
         by Scott Klement.
v2.01 - Added file reorganization.
        Added REDO option to G4MSREGSVC command to allow you to re-register a 
         a service if the refresh token becomes invalid.
v3.00 - Added scope of *OFFICE365EMAIL which allows sending emails using Microsoft
         APIs included in the F.G4MSMAIL subprocedure.  This requires registration
         of the G4MSMAIL addon.
        Included GETURI v6.00 in the G4MS library for compatibility reasons.  When
         using this software make sure if you have GETURI in another library it is 
         not above G4MS in your library list.
        Updated the registration of services so you don't need to copy and paste 
         codes from a web page back to the green screen.  Requires internet
         connectivity.
v3.10 - Updated G4MSMAIL to v2.00.
        Removed YAJLR4 *SRVPGM and made it Bind by Copy instead for compatibility
        Added a log file for sending email named G4MSMLGPF.  
        Added #g4ms_resendMail() function to allow user to resend a mail if it 
         ended in error and the email was created.  You must provide the unique
         ID of the email to resend (which can be found in the log file) and the
         .json file created during the email (also in the log file) attempt must 
         still exist.
        Renamed constants in the P.G4MS /COPY memeber by appending g4ms_ to the
         beginning so they won't conflict with other possible constant definitions.
        Added unique_id settable parameter.  This can be used to set the unique ID
         of the email being sent by the user.  If this is not set, the system will 
         create a unique ID.  Note, this ID MUST not exist in the G4MSMLGPF file 
         to be unique.
        Updated the #g4ms_sendMail() function to optionally return the unique ID
         of the email that was sent.
        SP162706 - Updated F.G4MSMAIL and F.G4MSDRV so the ID is case insensitive.
v3.11 - Updated registration program to use lower case for all IDs.
        SP160705 - Updated F.G4MSMAIL so if it errored out before refreshing a  
         token from a connection error the email is still able to be
         resent using MTG4MSLOG.
v4.00 - Added G4MSRMAIL addon which allows you to retrieve email messages and their
         attachments/embedded objects via a command interface or ILE subprocedures.
v4.10 - Updated to use GETURI v6.20.
        SP161201 - Updated G4MSMAIL so that when the \n sequence is used in 
         a message it is converted to a new line, like MAILTOOL
         does already.
v4.20 - Updated GETURI to v7.00 to allow non-strict SSL communications.
v4.30 - Added the following subprocedures:
         - #g4msmail_init() - Initialize G4MSMAIL
         - #g4msmail_loadDefaults() - Load defaults from a configuration file.  
            When using this option you must set the configuration file using
            #g4msmail_setValue('configuration_file':<cfgfile>)
         - #g4msmail_dumpSettings() - This will produce a JSON file in the temp
            directory containing the values of the variables used
        New paramters for #g4msmail_setValue():
         - dump_file - Set the dump file path and name
         - configuration_file - Set the configuration file path and name.  If the value
           *DFT is used it will look for a file named 
            /bvstools/g4ms/config/<userid>/defaults.json
           Where <userid> is the user id of the person running the application.  If a file
            isn't found it will use
            /bvstools/g4ms/config/defaults.json
        Updated application so that all files created use the temporary directory 
         specified instead of just /tmp. /tmp is the default temporary directory.
        If the email ends in error, along with the other debug files a configuration  
         file is created using #g4msmail_dumpSettings().
        #g4msmail_resendMail() will attempt to find the .json config file to use
         when resending emails.
        Updated so that the port used for communications is not hard coded.  Instead
         it will use the port in the G4MSSVCPF file URLs.
        SP170516 - Error retrieving messages would throw a pointer error.
         This was caused because some recipient data didn't include
          and email address all the time.  Fixed.
         Added retrieval of recipient names as well as addresses.
        SP170520 - Was only retriving 10 messages (MS pagination).  Updated 
         so it would get all messages that match criteria.
        SP170605- Updated G4MSMAIL to v3.11.
         Updated F.G4MSMAIL so when you are sending emails if an 
          attachment is over a limit it will throw an error instead
          of ignoring the attachment.
         Added data area G4MSMAXASZ that holds the maximum attachment
          size that can be used (in bytes).  Default to 30mb.  MS
          servers seem to have a problem with anything bigger
          so if this is increased do so at your own risk.
         Added GETURI v7.10.
         Fixed issue with base64 encoding when file already existed.
v4.50  - Updated GETURI to latest version.
         Renamed YAJL so it wouldn't conflict with other versions of YAJL
          that may be already installed.
v4.60  - Updated refresh token process to use new refresh token each time.
         Updated callbacks to all HTTPS vs HTTP.
         Updated registration link to HTTPS.
v4.70  - Update GETURI to v8.30.
v4.80  - Updated F.G4MSMAIL so that when processing emails from a mailbox
          if the encoded size of the part was bigger than the max size
          to throw an error.  Otherwise a space offset error could occur.
         SP180828 - Fixed pointer error when certain values weren't passed in the
          JSON data from the API.
         SP190328 - Fixed issue when running system CCSID of 65535 and base64 encoding
            error for attachments.
v5.00  - Deprecated F.G4MSDRV functions.  Replaced with F.G4MSOD functions which use the
          newer Microsoft Graph functionality.  The names of the subprocedures have also
          changed and may require updating of applications that used the old F.G4MSDRV
          functions.
         Updated GETURI to v10.02
         Added licensing required for base F.G4MS product.  
         Made F.G4MS service program available for use by 3rd parties.
         Require V7R2 or higher OS version.
         SP191121 - Added error checking to file upload so if there was an error
           while reading the file it would report the error instead of
           a generic error.
v6.00  - Updated F.G4MSMAIL service program to use the new Microsoft Graph APIs for email
          sending and retrieval.  Because of this update, users will need to re-register
          with their accounts and the service(s) they are using using the G4MSREGSVC
          command.
         Removed ability to use proxy with the override parameters for GETURI.
         Removed :443 from URLs in G4MSSVCPF file.
         For fields written to the G4MSMHPF file the labels now start with a lowercase
          letter instead of an uppercase letter to match the labels used by the new
          MS Graph API. Example: ToRecipient is now toRecipient.
v7.00  - Updated GETURI to v11.00.
v7.10  - Increased size of token fields in G4MS001PF from 2kb to 4kb.
         Added G4MSSMTP command which allows you to resend emails that errored out with
          G4MS using MAILTOOL Plus.
         SP201202 - Added extra error checking to G4MSUPLOAD command.  Updated version
          of G4MSDRV to v4.01.
v7.20 -  Updated GETURI to v11.00. 
         Added #g4msmail_forwardMail() function to F.G4MSMAIL service program.  This function
          allows you to forward an email to one or more TO addresses (CC and BCC not supported
          by MS at this time).
          Example:
           rc = #g4msmail_setValue('id':'bvstone@bvstools.onmicrosoft.com');       
           rc = #g4msmail_setValue('message':'Forwarding Comments');           
           rc = #g4msmail_setValue('message_id':MSMessageID);    
           rc = #g4msmail_addRecipient('bvstone@bvstools.com');                    
           rc = #g4msmail_forwardMail(ID:errorMsg);   
          The "message" settable variable is optional.
         Added the FILTER paramter to the G4MSLSTMM command, and also added the settable      
          variable "filter" to the #g4msmail_listMessages() function.
          With this new feature you can enter a filter query (encoded where necessary) 
          to change the results of the messages that are retrieved.  
          See https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter 
          for more information on buidling filter statements.     
         Examples of FILTER paramter on G4MSLSTMM command:

         contains(subject,'monday')                              
                                                        
         This will search for messages with the word monday (case insensitive) in the 
         subject of the message.     

         receivedDateTime+ge+2021-01-05T17:10:00Z               
                                                       
         This will search for messages with a received date and time greater than or 
         equal to January 5, 2021 17:10 UCT (11:10am CST)     
       
         rc = #g4msmail_setValue('filter':'contains(subject,''red'')');

         This will search for messages with the word "red" (case insensitive) in the
         subject of the message. 
         SP210116B - Added internet_message_id and internet_message_id_domain
           to settable values.  These are used for setting the message ID
           of the email.
         SP210127 - Updated #g4msmail_listMessages() function to not remove debug files
            if there is an error reading the JSON or if the JSON itself 
            contains an error
         SP210129 - Updated the dump process to make sure there is an ID in the filename.
           Added extra debugging to #g4msmail_listMessages() so if there is an 
            error parsing the JSON we will see the file name.
         SP210129b - Updated GETURI calls to also check for "E" code returned instead of 
            just %error after calling
         SP210316b - Added registration option method of *USERPW that allows you to 
             register for a service using only the account ID's password.  This
             option is valid for organizations only, not personal accounts.
         SP210317 - Updated *USERPW option so that user and password are URL encoded when
             sending to Microsoft.
         SP210326 - Updated F.G4MSMAIL service program to include #g4msmail_replyToMail()
             which allows you to reply to an email (using a message ID) with a  
             simple comment or a message.  If you use a message, the original
             email will not be included in the reply unless you specifically
             add it.  See documentation for more details.
         SP210420 - Fixed issue when registering a new ID.  It was saying the ID/service
             wasn't found.
         SP210610 - Added wildcard processing for attachment files.  Wilcards can be
            in the format *wildcard, wildcard* and wild*card.
v7.21 -  Updated GETURI to v11.00 sp210713
         SP211101 - Updated so that when retrieving mail labels it would process
            the next page(s) (MS updated to have pagination).
v7.30 -  Updated GETURI version to v11.00 sp211121
         Added the following functions to the F.G4MSOD (One Drive) service program:
          #g4msod_getItemID - Retrieve the unique ID for an item on the drive.
          #g4msod_delteItem - Delete (move to recycle) an item from the drive.
          #g4msod_downloadItem - Download an item from the drive.
          #g4msod_getShareableLink - Get a shareable link for a drive item.
          #g4msod_removePermissions - Remove permissions granted by the 
           get shareable link function.
          #g4msod_addRecipient - Add recipient to list of people who will 
           receive a sharing invitation from the following function.
          #g4msod_sendItemInvite - Send a sharing invite to a list of recipients.
        SP211221 - Updated so @ in requests would be corrent for different CCSID.
        SP211222 - Updated GETURI to v11.10.
           Updated the upload function to use the new *STMFRAW option
            in GETURI.
v8.00 - Updated GETURI to v12.00
        Removed hashtags (#) from the front of function names for better
         compatibility with other code pages.
        Updated bug in g4msmail_dumpSettings() where it was making invalid JSON.
        SP211230 - Updated program G4MSSMTP to use the new MAILTOOL function 
         without the beginning hashtag.
        SP220131 - Updated F.G4MSMAIL when dumping json to use return_address
         tag instead of just return which ended up causing an error.
        SP220323 - Updated GETURI to v12.00 SP220201
         Updated Upload function to allow zero byte file uploads.
        SP220326 - Updated List Files function so when there was an error 
            (such as no files found) it would remove the data files
            if debug wasn't turned on.  Previously it was leaving
            .json and .json.hdr files in the /tmp directory.
v9.00 - Added functions g4ms_setValue(), g4ms_resetValues(), g4ms_getRegistrationURL() and
         g4ms_exchangeCodeForToken().  These are used so that instead of using the 
         G4MSREGSVC command, you can retrieve a URL that can be displayed in your own
         application that the user can follow to register a service.  See more details
         in the documentation at: 
         https://docs.bvstools.com/home/greentools-for-microsoft-apps/g4ms-documentation/g4ms-base-commands
        Updated the callback to ws.bvstools.com to retrieve the Microsoft OAuth Code to use
         SSL.
v9.10 - Added ability to set group_id or group_name for most of the OneDrive functions.   This
         means in addition to working with your local OneDrive files you can also access
         Group/Site files.
        Added Group ID to file G4MSDRVPF.  When listing files only files for the user and specific
         Group will be cleared first.
        Added g4ms_getGroupID() function to the F.G4MS service program.
        Fixed a couple cleanup issues when errors occurred
        Added more sample programs to QRPGLESRC in G4MS library.
        NOTE: To work with groups you will need to re-regsiter any accounts for the *ONEDRIVE365
         service as this requires new scopes/authorities.
v9.11 - Updated G4MSREGSVC and ILE modules for registration to make adding the scopes for Groups
         optional.  The G4MSREGSVC command now has the GROUP parameter and for the 
         g4ms functions g4ms_getRegistrationURL() and g4ms_exchangeCodeForToken() have
         a settable value named "register_groups" that will accept either *YES or *NO.
v9.12 - Added function g4msmail_sendMailMime() to the F.G4MSMAIL service program.  This
         new function allows you to specify a MIME file to use as the email to send.
         Right now, because of Microsoft's limits and the Graph APIs, the size of the email
         is limited to 4MB. 
v9.15 - Added *OUTLOOKSMTP to the G4MSSVCPF (Service Master) file so that users can be set up
         to use the XOAUTH2 method when communicating over the outlook.office.com SMTP server.
         To use this method specify *G4MS_XOAUTH2 for the Authentication User (AUTHUSER) 
         parameter.  Example:
         MAILTOOL TOADDR(bvstone@test.com) FROMADDR(bvstone@test.onmicrosoft.com) 
          SUBJECT(test) SENDWITH(*MAILTOOL) MAILRTR(outlook.office365.com) 
          USERTR(*ONLY) MXLOOKUP(*YES) SSL(*TLS) PORT(587) 
          AUTHUSER(*G4MS_XOAUTH2)   
         SP220929 - Updated F.G4MS so on the g4ms_exchangeCodeForToken() function
          we are now passing the scope to Microsoft when getting a token.  
         SP221111 - Updated Green Screen registration method to include scope when
          exchanging code for token.
         SP221129 - Updated g4msmail_sendMail() so that it wouldn't delete the json
            config file if there was an error.  This was causing problems
            with resending.  If you are using MAILTOOL you should also make
            sure you update to MAILTOOL v12.50 SP221129b or higher as well.
         SP230329b - Updated so you can specify a footer file to include in the email.
            To do this set the g4msmail_setValue() function to set the value
            of footer_stream_file to the qualified path of the file in the 
            IFS to use as the footer.
         SP230827b - Found bug in list files function where user ID would be blank
            if it ran across an error listing subfolders.  Fixed.
v10.00 - Updated upload function to be able to upload files larger than 2GB with 
          the different IFS APIs.
         Updated GETURI to v13.00.
         SP240718 - Updated F.G4MSOD so that when uploading a file and there is
            and error and debug is on the files are not removed from
            the work directory.
         Removed authorization from PUT when uploading files which
            caused random errors.
v10.01 - Change max size for MIME file from 4mb (4194304) to 150mb (157286400) 
          in data area G4MSMAXMSZ.
v11.00 - Included G4MSCAL v1.00.
         Updated GETURI to v13.15.
         Updated F.G4MS to require a service parameter when requesting a Group ID using
          a Group Name.
         Updated F.G4MSOD to include a service parameter for the requirement above.
         Updated G4MSSVCPF to include a record for the *CALENDAR service.
         Included sample program source G4MSCALT in QRPGLESRC.
v11.00a- Updated REGTOOL and REGCHECK to include G4MSCAL
v11.10 - For G4MSMAIL updated so debug and trace files would have the same unique
          ID for easier identification of files required for support.
         Included ID in job log.
         On an error, debug and work files will not be deleted when sending emails
          and the output and debug files will be listed in the job log.
         SP251111 - Allow keyword "from_email" to be used to set the from email
           address as well as just "from".
         Load defaults if a configuration file is set when sending
           and original email.
         Added variables set by configuration file in job log if
           debug is turned on.
         SP251114- Updated attachment processing so a fully qualified path
           isn't required.
                   
-=-=-=-==-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

                   DISCLAIMER OF WARRANTY

 THIS SOFTWARE IS SOLD "AS IS" AND WITHOUT WARRANTIES AS TO
 PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER
 EXPRESSED OR IMPLIED. BECAUSE OF THE VARIOUS HARDWARE AND SOFTWARE
 ENVIRONMENTS INTO WHICH THIS PROGRAM MAY BE PUT, NO WARRANTY OF
 FITNESS FOR A PARTICULAR PURPOSE IS OFFERED.  GOOD DATA PROCESSING
 PROCEDURE DICTATES THAT ANY PROGRAM BE THOROUGHLY TESTED WITH
 NON-CRITICAL DATA BEFORE RELYING ON IT.  THE USER MUST ASSUME THE
 ENTIRE RISK OF USING THE PROGRAM.  ANY LIABILITY OF THE SELLER
 WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF
 THE PURCHASE PRICE.

       If you do not agree, please do not use this product.


-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=