Web DataWindow

1
IA317Building A Web DW Component
Larry Cermak 630 428-2650 lcermak_at_ctpartners.com w
ww.ctpartners.com
2
About Your Instructor

• VP of Technology, Corporate Technology Partners,
  Inc.
• Member of Team Sybase
• Writer for Sybase Developer Network and
  PowerTimes magazine
• CPD Professional
• CPD Review Board Committee Member
• 1997 Chicago PowerBuilder User Group VP
• Started building systems in 1984
• PowerBuilder development since version 2

3
About Your Instructor

• I believe in the KISS methodology
• (K)eep
• (I)t
• (S)imple
• (S)tupid

4
Corporate Technology Partners

• Offices in Denver, Chicago, and Connecticut
• Sybase Premier Channel Partner
• eMap Partner
• Consulting and mentoring services
• Training
• EAStudio
• EAServer
• Web DataWindow
• 3 Members of Team Sybase on staff

5
Introduction

• How technical will this session be?
• Detailed code and techniques
• Intended for beginners and experienced developers
• Sample code will be explained
• Lots of examples
• Real world techniques, not necessarily what the
  textbooks say!

6
Introduction

• Audience participation encouraged!
• Feel free to ask questions.
• Interaction makes the session more exciting.
• No question is stupid!!!
• I will make it as lively as possible!

7
Who Is In Attendance

• Managers vs developers
• PowerBuilder experience
• Less than 6 months
• Less than 1 year
• 1-2 years
• More than 2 years
• More than 5 years
• Feel free to ask questions!

8
Summary Of Course

• Purpose of This Presentation
• Use of Web DataWindows
• When to Customize
• Building a Component From Scratch
• Customizing the HTMLGenerator Component

9
Purpose of This Presentation
10
Purpose of This Presentation

• We Need More Power !

11
Purpose of This Presentation

• The Web DataWindow is a statement from Sybase
  about the future of PowerBuilder
• However, this is version 1 of the Web DataWindow
• We need MORE POWER!

12
Purpose of This Presentation

• The HTMLGenerator component was intended to be an
  example of how to build a Web DataWindow
  component
• The code is provided in PowerBuilder\code\exampl
  es\html\pbdwrmt.pbl
• This is a great start for moving a PowerBuilder
  application to the web
• Once you start building an application that uses
  Web DataWindows, you will quickly realize that it
  does not have all the functionality you need !

13
Use of Web DataWindows
14
Use of Web DataWindows

• Just because Sybase has given us this tremendous
  technology does not mean we have to use it
  everywhere!

15
Use of Web DataWindows

• Something to consider is when to use DataWindows
  to build web applications and when not to not use
  them
• There is no correct answer for this question
• It depends on several things
• The application you are building
• The type of functionality necessary
• Design standards
• Remember that you do not have to build an entire
  application of Web DataWindows
• Sometimes a simple PowerDynamo script is all that
  is necessary

16
Use of Web DataWindows

• Some recommendations for when NOT to use a Web
  DataWindow
• To display static text
• To display a simple database query with basic
  formatting
• If you want to be able to use functionality that
  has to do with browser events that are not yet
  implemented with the Web DataWindow
• For example, mouseover and mouseout
• The following screens show mouseover
  functionality to display a text message about a
  status
• It was not implemented with a DataWindow for this
  reason

17
Use of Web DataWindows
18
Use of Web DataWindows
Displayed as the mouse passes over the status
19
Use of Web DataWindows

• Some recommendations for when NOT to use a Web
  DataWindow, OR to build a customized component
• If you want to embed HTML tags in text for such
  things as formatting
• ltBRgt as an example
• The generator overrides these tags, so they are
  not useful in the output
• This is supposed to be changed in PowerBuilder 8

20
Use of Web DataWindows

• Some recommendations for when TO use a Web
  DataWindow
• You want to move an existing PowerBuilder
  application to the web
• Be careful, dont assume every DataWindow will
  look nice in a browser
• Remember browser applications process differently
  than Client/Server applications
• This will probably require design changes
• Data entry screens
• The DataWindow is easier than writing the HTML
  yourself
• It is also easier to interface with the database
• Queries

21
When To Customize
22
When To Customize

• This is a big question
• Should I customize right away?
• Should I wait until I get some experience with
  EAServer?
• Should I wait until version 2 of my application?
• Does the HTMLGenerator component provide all the
  functionality I need?

23
When To Customize

• There is a lot to learn about web applications
  before building a Web DataWindow component
• Web servers
• Web processing vs client/server processing
• HTML
• JavaScript
• Oh yes, dont forget about EAServer
• Definitely take the time to do the research

24
When To Customize

• Recommendations for Web DataWindow components
• 1) Take a look at the HTMLGenerator component
  code to see what Sybase has done
• 2) Decide whether you want to build on top of
  that or start from scratch
• 3) Decide whether you want to inherit from their
  code
• At TechWave1999 Sybase demonstrated the Alpha of
  PowerBuilder 8
• It looked like they will be adding more
  functionality to that component so inheriting
  from it might not be a bad idea

25
When To Customize

• Im sure someone will ask what I, and CTP
  recommend to our clients
• I chose to use the code in the HTMLGenerator
  component as the starting point
• Removed logic that I felt was unnecessary or had
  a better approach
• Added functionality that was necessary for our
  systems and client needs

26
When To Customize

• Whats missing from the HTMLGenerator component?
• Here are some of the things missing
• Loading dropdown DataWindows
• InsertRow method
• The generator does create a client-side InsertRow
  function, but it causes a page refresh
• Required field functionality
• Adding a new row, with default values, if a
  retrieve returns 0 rows
• Data caching for dropdown DataWindows
• GetValue server-side method
• Better Netscape generation

27
When To Customize

• So whats the bottom line?
• Definitely build or customize the HTMLGenerator
  component
• You will learn about how CORBA components work,
  especially in EAServer
• This can only make your applications better
• You will know how to provide a work around if
  there is something missing or lacking from the
  functionality provided by Sybase

28
When To Customize

• Soooooooooo, whats next...

Get your tools out and lets start building !
29
Building a Component From Scratch
30
Building a Component From Scratch

• This is not magic !
• The Web DataWindow is nothing more than a
  DataStore down deep
• A component has the functionality to set the
  transaction object, set the dataobject,
  transaction, etc.

31
Building a Component From Scratch

• All we have to do is investigate and dissect the
  code in the HTMLGenerator component

32
Building a Component From Scratch

• The generation of HTML is all within the
  PowerBuilder Virtual Machine (VM) at this point
• Take a look at the Generate method code from the
  HTMLGenerator component
• string ls_result
• if ib_trace then of_log_enter("Generate()")
• ls_result ids_datastore.Describe("DataWindow.Dat
  a.HTML")
• if ib_trace then of_log_exit("Generate(), length
  " String(Len(ls_result)))
• of_completeWork()
• return ls_result

33
Building A Component From Scratch

• The main line of code is a PowerScript Describe
  function call
• ids_datastore.Describe("DataWindow.Data.HTML")
• So with that knowledge, it is easy to move
  forward building a component
• OK, Ive been doing this since it was first put
  into the beta!
• Like anything else, once you have done it for a
  while it is easy!

34
Building a Component From Scratch

• The approach we will take to build a component is
  as follows
• Each step will be a new method (function) that we
  will build upon
• Steps
• Step 1
• Hard-coded data source and DataWindow object to
  retrieve a DataWindow and generate the HTML
  (of_dw1)
• Step 2
• Specify the browser type
• Step 3
• Make the DataWindow handle updates

35
Building a Component From Scratch

• First, we create a Jaguar component

36
Building a Component From Scratch
Informational screen
Library to create the object into
37
Building a Component From Scratch
PowerBuilder component name
Jaguar component name
38
Building a Component From Scratch
Jaguar server information
Jaguar package name
39
Building a Component From Scratch

• Provide the Jaguar connection information
• Provide the package name
• Click on the ellipse to choose an existing
  package

40
Building a Component From Scratch
41
Building a Component From Scratch

• Specify the component type
• Standard
• Enables the transaction, instance pooling, and
  object lifespan options
• This is the option for a Web DataWindow component
• Shared
• Used to allow multiple clients to share state
  information
• Provides access to common data so that it does
  not have to be retrieved by each client
• Think about data caching in 2-tier computing

42
Building a Component From Scratch

• Specify the component type
• Service
• Performs background processing for Jaguar clients
  and other Jaguar components
• These are loaded when the server is started

43
Building a Component From Scratch
44
Building a Component From Scratch

• Instance pooling options
• Supported
• The component is pooled after use so that another
  instance might not have to be created
• Creating an instance of an object is an expensive
  operation
• Not supported
• Pretty self explanatory
• Component timeout
• Specifies the length of time that the component
  instance can be idle between method calls before
  being automatically deactivated

45
Building a Component From Scratch

• Another note on instance pooling
• Leave pooling turned off for development
• It locks the PBL and requires Jaguar to be
  restarted in order to change a DataWindow object
• Remember to turn it on before deployment
• Occasionally Jaguar still locks PBLs during
  development with pooling off

46
Building a Component From Scratch
47
Building a Component From Scratch

• Transaction support options
• Not supported
• Never executed as part of a transaction
• Supports transaction
• Can execute as part of a Jaguar transaction, but
  it is not required
• Will not begin a transaction
• Will use an existing transaction if called from
  another component that is in a transaction

48
Building a Component From Scratch

• Transaction support options
• Requires transaction
• Always executes in a transaction
• Will create a new transaction
• Will use an existing transaction if called from
  another component that is in a transaction
• A Web DataWindow component requires a transaction
  since there is database activity
• Requires new transaction
• Will always create a new transaction
• Auto Demarcation/Deactivation
• If checked, indicates a stateless component

49
Building a Component From Scratch
50
Building a Component From Scratch

• Component interface options
• Expose user events as methods
• In the CORBA IDL
• Expose public instance variables
• As accessor methods in the CORBA IDL
• Allow null variables in method arguments
• Must specify this if you pass null arguments

51
Building a Component From Scratch

• Component interface options
• Use of unsupported datatypes generates an error
• PowerBuilder will warn you if you code something
  that is not valid in Jaguar
• Jaguar validation checks public instance
  variables and public functions for
• system types
• visual types
• structures
• and any variables

52
Building a Component From Scratch
53
Building a Component From Scratch

• Debugging and live editing options
• Remote debugging
• Uses the PowerBuilder debugger to step through
  the component that exists in Jaguar
• Definitely a powerful feature!
• Live editing
• The project will automatically be built each time
  the user object is saved
• This is a development option so you dont have to
  generate the project each time you make a change
  to the NVO

54
Building a Component From Scratch
Name of the project that will deploy this
component to Jaguar
55
Building a Component From Scratch
56
Building a Component From Scratch

• Dynamic library options
• Build consolidated dynamic library
• The PBD will contain referenced objects in all
  check libraries
• Separate
• Include unreferenced objects in consolidated PBD
• Consolidated PBD file name
• Resource file name

57
Building a Component From Scratch

• Note about method function overloading
• The IDL does not support it
• However, the component generator gets around this
  by doing the following
• Appending 2 underscores (__) plus a unique suffix
  to the method name that will be overloaded
• When the stubs or proxy objects are generated,
  Jaguar strips off the IDL suffix so the method
  can be accessed by its correct name
• Since __ is a reserved delimiter, dont create
  names that contain it

58
Building a Component From Scratch
59
Building a Component From Scratch

• What does that give us?
• A NVO that will be deployed as a Jaguar component
• n_techwave
• A project that will deploy the component into
  Jaguar
• p_techwave
• What do we do next?

60
Building a Component From Scratch

• Add a method (function) called of_techwave1
• No arguments
• Returns a string
• The assumption is that a DataWindow called
  d_department already exists
• This is not how to build a DataWindow, so I wont
  bore you with those details!
• The EAS Demo DB V3 data source will be used for
  this entire presentation

61
Building a Component From Scratch

• datastore lds_department
• string ls_html,ls_rc
• SQLCA.DBMS"odbc"
• SQLCA.dbparm"connectstring'dsneas demo db v3'"
• CONNECT Using SQLCA
• if SQLCA.SQLCode lt 0 then return ""
• lds_department CREATE datastore
• lds_department.dataobject "d_department_techwave
  "
• lds_department.SetTransObject(SQLCA)
• lds_department.Retrieve()
• ls_html lds_department.Describe("DataWindow.Data
  .HTML")
• DESTROY lds_department
• Disconnect Using SQLCA
• return ls_html

62
Building a Component From Scratch

• Save the object
• Now we have to build a project to deploy this to
  Jaguar as a CORBA component
• The project painter does this for us
• If it was not this easy, PowerBuilder 7.0 would
  not be as successful
• Easy is a good thing, thank you Sybase!

63
Building a Component From Scratch
Change it to a non PowerBuilder naming convention
Default
64
Building a Component From Scratch

• After the component is successfully deployed to
  Jaguar, it will appear in the Jaguar manager
• Package TechWave
• Component DataWindow
• If you already had Jaguar Manager running, you
  will need to refresh it before you can see this

65
Building a Component From Scratch
Component method
66
Building a Component From Scratch

• After the component has been created, you must
  create the stubs
• This is done from Jaguar Manager
• RMB on the package name
• Choose Generate Stub/Skeleton
• Select Generate Stubs Java Stubs
• This is because we did a java.CreateComponent to
  create the component from PowerDynamo

67
Building a Component From Scratch
68
Building a Component From Scratch

• The Java stubs must be compiled
• The .java files are created in a directory
  structure where Jaguar is installed
• d\sybase\Jaguar CTS 3.0\html\classes\packagename
• javac is the Java compiler
• javac .java
• Make sure the classpath setting contains the
  following path or it will not compile
• d\sybase\Jaguar CTS 3.0\html\classes
• A successful compile is indicated with no
  messages, the prompt comes back

69
Building a Component From Scratch

• Now we need a few lines of server-side JavaScript
  to access the component
• ltHTMLgt
• ltBODYgt
• lt!--SCRIPT
• dwLocal java.CreateComponent("TechWave/DataW
  indow", "iiop//localhost9000", "jagadmin", "")
• document.write(dwLocal.of_techwave1() )
• --gt
• lt/BODYgt
• lt/HTMLgt

70
Building a Component From Scratch
71
Building a Component From Scratch

• Just to prove this works in Netscape as well, the
  following screen shows the same page in Netscape
  4.7
• Notice the display is not as good
• Making your applications work in both browsers is
  a pain
• This is because the browsers are different
• Like everything else we have Microsoft
• and the rest of the world
• Please do not develop only in IE and then assume
  your application will look, and work, the same
  way in Netscape
• My presentation on design considerations covers
  this in great detail

72
Building a Component From Scratch
73
Building a Component From Scratch

• Notice that the screen looks OK, but could be
  better
• Buttons are not the same size
• Buttons do not line up
• Height of the text and columns is quite large
• Since we did not tell the component the type of
  browser and version, it generated non browser
  specific HTML
• Lets now tell the component what type of browser
  we have

74
Building a Component From Scratch

• Add a second function to the object called
  of_techwave2
• string argument, s_browser
• For simplicity I copied the code from
  of_techwave1 and will add the logic to tell the
  DataStore the browser type
• lds_department.Modify("DataWindow.HTMLGen.Browser
  '" s_browser "' ")
• Once this is done, we need to do the following
• Redeploy the component to Jaguar
• Since the interface changed, generate and compile
  the stubs
• Depending on the web server, may have to bounce it

75
Building a Component From Scratch

• datastore lds_department
• string ls_html,ls_rc
• //
• // connect to database
• //
• SQLCA.DBMS"odbc"
• SQLCA.dbparm"connectstring'dsneas demo db v3'"
• CONNECT Using SQLCA
• if SQLCA.SQLCode lt 0 then return ""
• lds_department CREATE datastore
• lds_department.dataobject "d_department_techwave
  "
• lds_department.SetTransObject(SQLCA)
• ls_rc lds_department.Modify("DataWindow.HTMLGen.
  Browser'" s_browser "' ")
• lds_department.Retrieve()
• ls_html lds_department.Describe("DataWindow.Data
  .HTML")
• DESTROY lds_department
• Disconnect Using SQLCA
• return ls_html

76
Building a Component From Scratch

• We will now call of_techwave2 and pass it an
  argument
• The argument of browser type and version is
  available as part of the HTTP request
• lv_browser document.GetServerVariable("HTTP_USER
  _AGENT")
• document.write("lv_browser" lv_browser
  "ltBRgtltBRgt")
• document.write(dwLocal.of_techwave2(lv_browser)
  )
• Notice we are displaying the result of the
  GetServerVariable request in the output

77
Building a Component From Scratch
78
Building a Component From Scratch

• Keep in mind that the browser type will not say
  Internet Explorer or Netscape Navigator
• The reason I am pointing this out is that this is
  the way to detect browser type so you can write
  specific browser functionality
• As an example, the CTP component can change the
  generated HTML if the browser is Netscape
• It does not look for Netscape in the HTTP
  request, it scans for MSIE and if it does not
  find it assumes it is Netscape
• The following slide is the same page in Netscape
  4.7

79
Building a Component From Scratch
Notice it does not say Netscape
80
Building a Component From Scratch

• So whats next?
• We will skip the basic stuff like passing
  arguments to set the transaction object, database
  connection, etc.
• Since it is PowerScript code we all know how to
  do that
• If we try and update this screen, an error will
  occur
• Why?
• Lets investigate
• The following screen shows the error that occurs

81
Building a Component From Scratch
Notice the error in the URL
82
Building a Component From Scratch

• Notice the error in the URL line
• 20ERROR20NO20SELF20LINK
• 20SPECIFIED!20
• So, how do we fix this?

83
Building a Component From Scratch

• There are 4 things necessary to make the Web
  DataWindow perform updates
• Changing the datastore variable to be an instance
• Setting the self link
• A method to apply the action of the HTML page to
  the server component
• JavaScript to get the parameters from the page
  and apply the action

84
Building a Component From Scratch

• Changing the datastore variable to be an instance
• Why?
• Because when we apply (or set) the action from
  the HTML page into the server component, the
  datastore must already exist so there is
  somewhere for the context to be applied to
• Note that when I do this, I will also code the
  connection to the database in the activate event
  and the appropriate cleanup in the deactivate
  event

85
Building a Component From Scratch

• Setting the self link
• Self link is required with an HMTL page in order
  to perform updates
• The online help states the following
• Specifies the URL and page parameters for the
  current page of the HTML DataWindow.
• The reason it is necessary is to retain any
  information passed into the HTML page
• This is because a page refresh occurs when an
  update occurs
• If Self link is not specified, the parameters
  will be lost
• Self like also can have arguments

86
Building a Component From Scratch

• The self link is set when the page is initially
  generated
• So we will copy of_techwave2, call it
  of_techwave3, and add 2 parameters
• s_selflink
• s_selflink_args
• Add 2 lines of code to the function
• ids_department.Modify("Datawindow.HTMLGen.SelfLink
  '" s_selflink "' ")
• ids_department.Modify("DataWindow.HTMLGen.SelfLink
  Args'" s_selflink_args "' ")

87
Building a Component From Scratch

• A method to apply the action of the HTML page to
  the server component
• Hitting an button with the action of update
  generates the HTML to post
• We need to apply this to the server component

88
Building a Component From Scratch

• Create a method called of_setaction with 2
  arguments
• s_action, s_context
• TransactionServer lts1
• int li_rtn
• li_rtn ids_department.SetHTMLAction(s_action,s_c
  ontext)
• this.GetContextService("TransactionServer",lts1)
• if li_rtn 1 then
• lts1.SetComplete()
• else
• lts1.SetAbort()
• end if
• return li_rtn

89
Building a Component From Scratch

• Javascript to get the parameters from the page
  and apply the action
• These parameters come from the generated HTML and
  indicate the action and context of the action
• For example, insert a row and use the information
  that was entered into the HTML form
• Once there is an action, call the of_setaction
  method
• This is placed in our server-side script

90
Building a Component From Scratch

• Get the parameters from the page
• lt!--SCRIPT
• function GetParam( envparam )
• for (el in document.value)
• if (el envparam)
• return document.valueenvparam
• return "undefined"

91
Building a Component From Scratch

• Apply the action to the server component
• lv_action GetParam("htmldw_action")
• lv_context GetParam("htmldw_context")
• document.write("action" lv_action
  "ltBRgtcontext" lv_context "ltBRgt")
• if (lv_action ! "undefined")
• lv_ret dwLocal.of_setaction(lv_action,lv_con
  text)
• document.write("of_setaction" lv_ret
  "ltBRgt")

92
Building a Component From Scratch
Notice there is no action when the page is loaded
93
When the update button is pressed, an action
occurs
94
Building a Component From Scratch

• ltHTMLgt
• ltBODYgt
• lt!--SCRIPT
• function GetParam( envparam )
• for (el in document.value)
• if (el envparam)
• return document.valueenvparam
• return "undefined"
• dwLocal java.CreateComponent("TechWave/DataW
  indow", "iiop//localhost9000", "jagadmin", "")
• lv_browser document.GetServerVariable("HTTP_
  USER_AGENT")
• document.write("lv_browser" lv_browser
  "ltBRgtltBRgt")
• lv_selflink document.name
• lv_args ""
• document.write(dwLocal.of_techwave3(lv_browser
  ,lv_selflink,lv_args) )

95
Building a Component From Scratch
More Power !
96
Customizing The Component
97
Customizing The Component

• Lets take one example and code it
• Loading dropdown DataWindows that have retrieval
  arguments
• Since this is PowerScript code, it is simple
• Open the nv_remote_datawindow object
• Create a new function, of_load_dddw
• 5 string arguments
• s_column, column name to load
• s_argument1, argument for the dddw
• s_argument2, argument for the dddw
• s_argument3, argument for the dddw
• s_filter, in case a filter for the dddw is needed
• returns int (1success, -1fail)

98
Customizing The Component

• DataWindowChild ldwc_1
• int li_rtn
• long ll_tot
• ids_datastore.GetChild(s_column,ldwc_1)
• ldwc_1.SetTrans(SQLCA)
• if ldwc_1.Retrieve(s_arg1,s_arg2,s_arg3) -1
  then
• li_rtn -1
• else
• li_rtn 1
• // if no records returned, then insert an empty
  one so they are not prompted
• ll_tot ldwc_1.RowCount()
• if ll_tot 0 then ldwc_1.InsertRow(0)
• end if
• //
• // if filter passed, apply it
• //
• if Trim(s_filter) ltgt "" AND Lower(s_filter) ltgt
  "null" then
• ldwc_1.SetFilter(s_filter)

99
Customizing The Component

• After the customization is complete, you need to
  deploy the new component
• Create a Jaguar component generator project
• Set the various attributed for the component
  based on your business rules
• Change the package and component name
• Package name, Web_DataWindow
• Component name, Web_HTMLGenerator
• Now review the new component in the Jaguar
  Manager
• Notice the method names are all lower case
• As mentioned earlier, if you want the case
  maintained, you have to edit the idl yourself

100
HTMLGenerator component
101
Web_HTMLGenerator component
102
Customizing The Component

• After the component has been created, you must
  create the stubs
• You need to do this anytime the interface changes
• This is done from Jaguar Manager
• RMB on the package name
• Choose Generate Stub/Skeleton
• Select Generate Stubs Java Stubs
• This is because we did a java.CreateComponent to
  create the component from PowerDynamo

103
Customizing The Component
104
Customizing The Component

• The Java stubs must be compiled
• The .java files are created in a directory
  structure where Jaguar is installed
• d\sybase\Jaguar CTS 3.0\html\classes\packagename
• javac is the Java compiler
• javac .java
• Make sure the classpath setting contains the
  following path or it will not compile
• d\sybase\Jaguar CTS 3.0\html\classes
• A successful compile is indicated with no
  messages, the prompt comes back

105
Customizing The Component

• Thats all there is to it
• Now we have MORE POWER!
• This was the premise of this whole presentation!

106
Questions

• Any questions
• Web DataWindow?
• PowerBuilder?
• PowerDynamo?
• Jaguar?
• PowerSite?
• JavaScript?
• Microsoft IE vs Netscape?
• Other?
• Comments
• About the course
• About the Sybase products

107
Thank You

• lcermak_at_ctpartners.com
• www.ctpartners.com
• 630 428-2650
• Web DataWindow Training
• Can be customized
• EAServer Training
• Consulting/Mentoring