pyARS - from python to ARS
##########################

===========================
Examples for usage of pyars
===========================

Transferring field attributes from one server to another
########################################################

In a project we wanted to bring over the helptexts from one form on one server
to another form on another server, for matching fieldids.

The task was to: fetch all fieldids from the original form, and then, for
each of those fieldids, retrieve the fieldinfo from the original server,
and set the helptext to a field of same fieldid on the target form.

::

    fromForm = 'form A'
    toForm = 'form B'
    numUpdates = 0
    from pyars import cars, ars
    aFrom=ars.ARS()
    aTo=ars.ARS()
    aFrom.Login('server1', 'user1', 'password1')
    aTo.Login('server2', 'user2', 'password2')
    fl = aFrom.ARGetListField(fromForm, 0, cars.AR_FIELD_TYPE_ALL)
    for i in range(fl.numItems):
        fieldId = fl.internalIdList[i]
        toField = aTo.ARGetField(toForm, fieldId)
        if aTo.errnr > 1:
            aTo.logger.info('Field %d does not exist on target form %s' % (fieldId,
                                                                         toForm))
            continue
        fromField=aFrom.ARGetField(fromForm, fieldId)
        result = aTo.ARSetField(toForm, fieldId , helpText = fromField.helpText)
        if result > 1:
            aTo.logger.error ('Update to field %d on target form %s failed' % (fieldId, toForm))
        else:
            numUpdates += 1
    aFrom.logger.info('%d updates to fields on %s were successful' % (numUpdates, toForm))

As you can see, this little script assumes that the first ARGetListField
throws no error. But then, in the loop, the error handling makes sure that
a field with the current fieldid exists on the target form, otherwise the
loop will "continue". Only after that check will the loop retrieve detail
information for this fieldid from server1 (again no error check), and
modify the field with the same fieldid and the helptext.

Export Field Attributes to a CSV file
#####################################

In another project, we needed a list of all fieldnames for a given form
together with their data types, in a CSV format.

::

    from pyars import ars, cars
    a=ars.ARS()
    a.Login('server', 'user', 'password')
    r=a.ARGetListField('User')
    fieldName = cars.ARNameList()
    dataType = cars.ARUnsignedIntList()
    r2=a.ARGetMultipleFields('User', r, fieldName = fieldName, dataType = dataType)
    output=['Fieldname;Type']
    for i in range(r2.numItems):
        output.append('%s;%s' % (r2.fieldList[i].fieldName, cars.ars_const['AR_DATA_TYPE'][r2.fieldList[i].dataType]))
    # create one long string
    text = '\\n'.join(output)
    # open a file for write access
    file=open('c:\\\\temp\\\\fields.txt', 'w')
    file.write(text)
    file.close()
    a.Logoff()

Here you can see the recommended way to handle string concatenation in Python:
do not add several strings (e.g. 'string1' + 'string2'), but rather
generate a list containing all strings and at the end use the join() function
to join all list elements into a single string.

ARGetMultipleFields (as all other ARGetMultiple functions) expect
a list of attributes that they should fetch from the server; pyARS by
default sets them all to None, so that when you specify nothing you will
receive nothing. Might sound strange, on the other hand that reduces load
on the server and network traffic...

In other examples we often created 'raw strings' for path information;
then we do not need to escape the backslash ('\\'). In this example I used
a normal string, but then you can see that you need to escape every occurance
of the backslash.

Other examples
##############

If you want your examples included in this section, please do
not hesitate to send them to us...